wjs-auditing-project

wjs-auditing-project

概述

全面审计项目状态。找出所有停滞、损坏或偏离计划的事项，然后在用户确认清单后统一修复。

严格分为两个阶段：

1. 调查 → 提交分组清单（只读；不提交、不合并、不推送）
2. 修复 — 仅在用户明确确认要做什么之后

绝不能合并这两个阶段。用户希望在采取任何行动之前先全面了解情况。“直接把所有问题都修好”可以作为确认，但仍须先提供清单，让用户过目。

适用场景

• “看看现在的项目到底出了什么问题” / “make it right” / “what's broken”
• “为什么我的反馈还没上线”
• “为什么很久没有新 build / 没提交 App Store”
• “有没有 PR / 分支没合”
• 离开一段时间后重新回到项目
• 发布 / 推送 TestFlight 前，确认没有遗留事项

阶段 1 — 调查（并行执行）

在一条消息中使用并行 Bash 调用运行所有只读检查。不要询问用户要运行哪些检查；全部运行。很多检查会显示“没有问题”——没关系，这些内容不必出现在清单中。

A. 工作区与暂存区

• git status — 是否有未提交的工作？
• git stash list — 是否有被遗忘的暂存？
• git branch -vv — 本地分支及其跟踪分支的领先 / 落后情况
• git log --oneline main..HEAD — 当前分支上有哪些内容不在 main 中？
• git fetch origin --prune && git log --oneline HEAD..@{upstream} — 远程有哪些内容不在本地？
• git branch -r --merged main 和 git branch -r --no-merged main — 仍未清理的远程分支

B. 未关闭 / 草稿 PR

• gh pr list --state open --json number,title,isDraft,mergeable,mergeStateStatus,updatedAt,author,headRefName
• 对于任何超过 7 天的 PR，或 mergeStateStatus ≠ CLEAN 的 PR：通过 gh pr checks <num> 记录未通过的检查
• 自动合并的机器人 PR（根据记忆：应用内反馈 → @claude PR → 自动合并）：gh pr list --author "app/claude" --state all --limit 20 — 是否有已合并但尚未进入 TestFlight 构建的 PR？是否有卡住的未关闭 PR？

C. CI / GitHub Actions

• gh run list --limit 20 --json conclusion,name,headBranch,createdAt,databaseId,event
• gh run list --status failure --limit 10 — 专门列出失败项
• 对于 main 或未关闭 PR 分支上的每个失败项：使用 gh run view <id> --log-failed | tail -100 记录实际错误

D. 已发布与未发布的工作（Cathier 的 iOS 专项检查）

• grep -E "MARKETING_VERSION|CURRENT_PROJECT_VERSION" *.xcodeproj/project.pbxproj | sort -u — 当前版本号和构建号
• git tag --sort=-creatordate | head -5 — 最近的发布标签
• git log --oneline <last-tag>..main — 自上一个带标签的版本发布以来的提交
• 检查 fastlane/ 配置和 fastlane/report.xml（如果存在），查找最近的 pilot / deliver 调用
• git log -1 --format="%ai %s" -- fastlane/ — 最近一次 fastlane 变更
• git log --all --grep="bump\|version\|build" -10 --oneline — 最近的版本号更新

E. 计划偏差

• 阅读 TODOS.md、CHANGELOG.md、APP_STORE_SUBMISSION_GUIDE.md、ROADMAP.md，以及 docs/plan*.md（如果存在）
• 对照已发布的提交检查计划事项——有哪些事项列出了但尚未完成？有哪些日期已经过期？
• grep -rn "TODO\|FIXME\|XXX" --include="*.swift" . — 源代码中的偏差标记

F. 应用 / 系统日志

• ls -t ~/Library/Logs/DiagnosticReports/Cathier* 2>/dev/null | head -5 — 应用最近的崩溃报告
• log show --predicate 'process == "Cathier"' --last 1d --style compact 2>/dev/null | grep -iE "error|fault" | head -20 — 最近的运行时错误（如果这台 Mac 上没有安装应用，则静默跳过）
• ls -t ~/Library/Developer/Xcode/DerivedData/*/Logs/Build/*.xcactivitylog 2>/dev/null | head -3 — 最近的构建尝试（检查文件是否存在及其修改时间；不要尝试解析）

G. 专门处理用户反馈

根据记忆：应用内反馈会创建由 @claude 发起的 PR，并自动合并到 main。要回答“为什么应用里没有我的反馈”：

1. 是否根据反馈创建了 PR？（gh pr list --author "app/claude" --state all）
2. 是否已合并？（检查 PR 状态）
3. 是否有比合并提交更新的 TestFlight/App Store 构建？ 如果第 3 项的答案是没有，这就是原因：已合并到 main，但从未构建/提交。

呈现检查清单

输出一份分组的 Markdown 检查清单。每项必须包含：问题所在、证据（数字/日期/文件路径），以及一项拟议操作，措辞要让用户可以回答是或否。按紧急程度分组：

## What I found

### 🔴 Blocking (these gate everything else)
- [ ] PR #42 "Add jokes redesign": 3 failing checks (SwiftLint, build, tests). Last commit 2026-04-30. → Read logs, fix, push?
- [ ] main is 7 commits ahead of last tag v1.4.0 (2026-03-22). No TestFlight build since then. → Tag v1.5.0 and prep release notes?

### 🟡 Open work
- [ ] Local branch `home-simplification` has 5 commits, no open PR, last activity 2026-05-08. → Open PR against main?
- [ ] Stash "WIP: brain trainer stats" from 2026-04-02. → Show diff and decide drop/apply?

### 🟢 Plan drift (TODOS.md / fastlane)
- [ ] TODOS.md line 14: "Submit App Store build by 2026-04-30" — overdue 11d, no `fastlane pilot` invocation since 2026-03-12.
- [ ] TODOS.md line 22: "Hook up haptics on streak page" — no matching commit on main.
- [ ] 2 auto-merged @claude PRs (#88, #91) from in-app feedback merged after last TestFlight build — user feedback shipped to main but not to TestFlight.

### Logs / errors
- [ ] 23 errors in last 24h matching "NSURLErrorDomain -1009" (offline path) — investigate or note as expected?
- [ ] 1 crash report from 2026-05-10 in DiagnosticReports — pull stack and triage?

### Looks fine
- Working tree clean, no orphan branches on origin, no failed CI on main this week.

最后写上：“想让我把这些都修好吗？还是挑一部分？或者先讨论某一项？”

阶段 2 — 修复（仅在用户确认后）

用户确认后（确认全部、部分项目，或“全部处理绿灯和黄灯项目，但不处理 App Store 那项”）：

1. 为每个已确认项目创建一个待办事项（TaskCreate）
2. 按以下顺序处理：CI 失败 → 分支合并 → 标签 → 版本号更新 → 发行说明 → 构建提示词
3. 一次处理一项；完成后立即标记，不要批量标记
4. 每次修复后，重新运行阶段 1 中对应的检查，确认问题确实已解决
5. 最后简短总结：已修复 / 已跳过 / 需要人工处理

可自主处理的事项

• 查看失败的 CI 日志、编辑代码、推送修复
• 使用 gh pr create 为尚未推送的分支创建 PR
• 查明失败原因后，使用 gh run rerun <id> 重新触发失败的运行（不要盲目重跑看似不稳定的失败；先找出根本原因）
• 如果用户针对该 PR 明确同意，使用 gh pr merge --squash --auto 合并无问题的 PR
• 在 project.pbxproj 中更新 MARKETING_VERSION / CURRENT_PROJECT_VERSION
• 添加 CHANGELOG 条目，使用 git tag 为发行版本打标签（用户确认前不要推送标签）
• 展示差异后，删除或恢复 stash

需要用户操作的事项

打印他们应运行的确切命令，并在前面加上 !：

• ! fastlane pilot upload — 提交到 App Store / TestFlight 时需要对二进制文件签名；必须由用户操作
• ! open Cathier.xcodeproj — 任何需要在 Xcode 归档界面中执行的操作
• 任何破坏性操作：git reset --hard、git push --force、删除分支

常见发现 → 标准修复

发现	标准修复
本地分支领先于 main，且没有 PR	基于 main 变基，推送，然后使用 gh pr create 创建 PR
PR 在相同步骤两次 CI 失败	查看失败日志，修复根本原因，不要盲目重跑
有未发行提交 + TestFlight 版本过旧	更新构建号、打标签、编写发行说明，并提示用户运行 fastlane pilot
Stash 超过 30 天，且上下文不明	向用户展示 git stash show -p <n>，询问是删除还是应用
TODOS.md 中的条目没有对应提交	提请用户确认：是已取消还是被遗忘？不要自行判断
自动合并的反馈 PR 比最近一次构建更新	应对方案是构建新的 TestFlight 版本，而不是继续修改代码
fastlane/ 没有改动，但计划显示 App Store 截止日期已过	提请用户注意截止日期和上次提交日期；由用户决定优先级

危险信号 — 停止

想法	事实
“我直接修复，跳过检查清单就行”	不行。用户明确要求先审查再确认。
“这个 PR 看起来可以安全合并，我来合并吧”	只有用户在回复中明确确认了这个 PR，才能合并。
“我用强制推送整理一下历史记录”	未经逐项明确确认，绝不这么做。
“我关闭那个卡住的 PR，整理一下吧”	先调查；相关工作可能仍可挽救。
“我代替用户提交到 App Store”	绝不这么做。打印 ! fastlane … 命令，然后停止。
“崩溃报告大概没什么问题”	拉取调用栈并提请用户注意，让用户决定。
“计划中的条目太旧了，肯定已经过时”	先询问。不要删除计划条目。

此用户 / Cathier 专属说明

• 默认工作目录：/Users/jianshuo/code/Cathier。无论从何处调用，都应遵守此设置。
• Cathier 是一款 SwiftUI iOS 应用，使用 fastlane/ 处理 App Store / TestFlight。
• 计划的唯一事实来源是 TODOS.md 和 APP_STORE_SUBMISSION_GUIDE.md。请同时阅读这两个文件。
• 备忘：应用内反馈 → app/claude 创建 PR → 自动合并到 main。因此，“为什么应用里看不到我的反馈”通常意味着 合并已经完成，但尚未生成新的构建版本。调查代码之前，请先核对 TestFlight 构建日期与 PR 合并日期。
• gh 已完成身份验证。已安装 fastlane（存在 Gemfile）。
• DESIGN.md 是视觉设计的唯一事实来源；提出与其冲突的 UI 修复方案时，务必指出冲突。