wjs-auditing-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

wjs-auditing-project

Overview

概述

Holistic project-state audit. Find everything that's stalled, broken, or diverged from the plan — then fix it together after the user confirms the checklist.

Hard two-phase split:

Investigate → present grouped checklist (read-only; no commits, no merges, no pushes)
Fix — only after the user explicitly confirms what to do

Never collapse the phases. The user wants to see the full picture before any action. "Just go ahead and fix everything" is fine as confirmation, but you still produce the checklist first so they can scan it.

全面的项目状态审计工具。找出所有停滞、故障或偏离计划的问题——在用户确认检查清单后再共同修复这些问题。

严格分为两个阶段：

调查 → 呈现分组检查清单（只读模式；不提交、不合并、不推送代码）
修复 —— 仅在用户明确确认要处理的内容后执行

绝不能合并这两个阶段。用户希望在采取任何行动前了解完整情况。“直接修复所有问题”可视为确认指令，但仍需先生成检查清单供用户查看。

When to use

使用场景

"看看现在的项目到底出了什么问题" / "make it right" / "what's broken"
"为什么我的反馈还没上线"
"为什么很久没有新 build / 没提交 App Store"
"有没有 PR / 分支没合"
Returning to a project after time away
Before a release / TestFlight push, to make sure nothing is dangling

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

Phase 1 — Investigate (parallel)

第一阶段 — 调查（并行执行）

Run all the read-only checks in one message with parallel Bash calls. Don't ask the user which to run; run them all. Many will return "nothing wrong" — that's fine, those just don't show up in the checklist.

通过一条消息中的并行Bash命令运行所有只读检查。不要询问用户要运行哪些检查；全部运行。许多检查会返回“无异常”——这是正常的，这些结果不会出现在检查清单中。

A. Working tree & stashes

A. 工作区与暂存内容

```
git status
```
— uncommitted work?
```
git stash list
```
— forgotten stashes?
```
git branch -vv
```
— local branches, ahead/behind tracking
```
git log --oneline main..HEAD
```
— what's on current branch not in main

git fetch origin --prune && git log --oneline HEAD..@{upstream}

— what's on remote not local

git branch -r --merged main

and

git branch -r --no-merged main

— remote branches still floating

```
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. Open / draft PRs

B. 已打开/草稿PR

gh pr list --state open --json number,title,isDraft,mergeable,mergeStateStatus,updatedAt,author,headRefName

For any PR older than 7 days OR with
```
mergeStateStatus
```
≠
```
CLEAN
```
: capture the failing checks via
```
gh pr checks <num>
```
Auto-merge bot PRs (per memory: in-app feedback → @claude PR → auto-merge):
```
gh pr list --author "app/claude" --state all --limit 20
```
— any merged but not yet in a TestFlight build? Any stuck open?

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
```
— failures specifically
For each failure on
```
main
```
or on an open PR's branch:
```
gh run view <id> --log-failed | tail -100
```
to capture the actual error

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. Released vs unreleased work (iOS specifics for Cathier)

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

grep -E "MARKETING_VERSION|CURRENT_PROJECT_VERSION" *.xcodeproj/project.pbxproj | sort -u

— current version + build number

```
git tag --sort=-creatordate | head -5
```
— recent release tags
```
git log --oneline <last-tag>..main
```
— commits since last tagged release
Check
```
fastlane/
```
config and
```
fastlane/report.xml
```
(if present) for last
```
pilot
```
/
```
deliver
```
invocation

git log -1 --format="%ai %s" -- fastlane/

— last fastlane change

git log --all --grep="bump\|version\|build" -10 --oneline

— recent version bumps

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. Plan drift

E. 计划偏差

Read

TODOS.md

CHANGELOG.md

APP_STORE_SUBMISSION_GUIDE.md

ROADMAP.md

docs/plan*.md

if any exist

Cross-reference plan items against shipped commits — what's listed but not done? What has a date that's already passed?

grep -rn "TODO\|FIXME\|XXX" --include="*.swift" .

— drift markers in source

读取

TODOS.md

、

CHANGELOG.md

、

APP_STORE_SUBMISSION_GUIDE.md

、

ROADMAP.md

、

docs/plan*.md

（如果存在）

将计划项与已提交的代码进行交叉对比——哪些计划项已列出但未完成？哪些计划项的截止日期已过？

grep -rn "TODO\|FIXME\|XXX" --include="*.swift" .

—— 源代码中的偏差标记

F. App / system logs

F. 应用/系统日志

ls -t ~/Library/Logs/DiagnosticReports/Cathier* 2>/dev/null | head -5

— recent crash reports for the app

log show --predicate 'process == "Cathier"' --last 1d --style compact 2>/dev/null | grep -iE "error|fault" | head -20

— recent runtime errors (skip silently if no install on this Mac)

ls -t ~/Library/Developer/Xcode/DerivedData/*/Logs/Build/*.xcactivitylog 2>/dev/null | head -3

— last build attempts (existence + mtime; don't try to parse)

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. User-feedback specifically

G. 用户反馈专项检查

Per memory: in-app feedback creates @claude PRs that auto-merge into main. To answer "why isn't my feedback in the app":

Was a PR created from feedback? (

gh pr list --author "app/claude" --state all

)

Was it merged? (check PR status)
Is there a TestFlight/App Store build newer than the merge commit? If 3 = no, that's the answer: merged into main but never built/submitted.

根据记忆：应用内反馈会创建@claude PR并自动合并到main分支。要回答“为什么我的反馈没出现在应用中”：

是否根据反馈创建了PR？（

gh pr list --author "app/claude" --state all

）

PR是否已合并？（检查PR状态）
是否存在晚于合并提交时间的TestFlight/App Store构建？如果第3步答案为否，那就是原因：已合并到main分支但从未构建/提交。

Presenting the checklist

呈现检查清单

Output one grouped markdown checklist. Each item must contain: what's wrong, evidence (numbers/dates/file paths), and a proposed action phrased so the user can say yes/no. Group by urgency:

undefined

输出一份分组的Markdown检查清单。每个条目必须包含：问题内容、证据（数字/日期/文件路径），以及可让用户回答是/否的建议操作。按紧急程度分组：

undefined

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?

PR #42 "Add jokes redesign"：3项检查失败（SwiftLint、构建、测试）。最后一次提交时间2026-04-30。→ 读取日志、修复问题并推送？
main分支比上一个标签v1.4.0（2026-03-22）领先7个提交。此后未生成TestFlight构建。→ 标记v1.5.0版本并准备发布说明？

🟡 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?

本地分支
```
home-simplification
```
有5个提交，未打开PR，最后活动时间2026-05-08。→ 针对main分支打开PR？
暂存内容"WIP: brain trainer stats"来自2026-04-02。→ 显示差异并决定丢弃/应用？

🟢 Plan drift (TODOS.md / fastlane)

🟢 计划偏差（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.

TODOS.md第14行："Submit App Store build by 2026-04-30" —— 逾期11天，自2026-03-12以来未调用
```
fastlane pilot
```
。
TODOS.md第22行："Hook up haptics on streak page" —— main分支上无匹配提交。
2个自动合并的@claude PR（#88、#91）来自应用内反馈，合并时间晚于上一次TestFlight构建——用户反馈已合并到main分支但未推送到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?

过去24小时内有23条匹配"NSURLErrorDomain -1009"的错误（离线路径）—— 调查还是标记为预期情况？
2026-05-10在DiagnosticReports中有1份崩溃报告—— 获取堆栈信息并分类处理？

Looks fine

无异常项

Working tree clean, no orphan branches on origin, no failed CI on main this week.


End with: **"想让我把这些都修好吗？还是挑一部分？或者先讨论某一项？"**

工作区干净，远程服务器上无孤立分支，本周main分支无CI失败。


结尾需添加：**"想让我把这些都修好吗？还是挑一部分？或者先讨论某一项？"**

Phase 2 — Fix (only after user confirms)

第二阶段 — 修复（仅在用户确认后执行）

Once the user confirms (full set, subset, or "all green and yellow but not the App Store one"):

TaskCreate a todo per confirmed item
Order: failing CI → branch merges → tags → version bumps → release notes → build prompt
Work them one at a time; mark done immediately, not in batches
After each fix, re-run the corresponding check from phase 1 to verify it's actually resolved
End with a short summary: fixed / skipped / requires-human

一旦用户确认（全部修复、部分修复，或“修复所有黄色和绿色项，但不处理App Store相关项”）：

为每个确认的项创建待办任务
执行顺序：失败的CI → 分支合并 → 版本标记 → 版本号更新 → 发布说明 → 构建提示
逐项处理；完成后立即标记，不要批量处理
每次修复后，重新运行第一阶段中对应的检查以验证问题已解决
最后给出简短总结：已修复 / 已跳过 / 需要人工处理

What you can do autonomously

可自主执行的操作

Read failing CI logs, edit code, push the fix
Open a PR with
```
gh pr create
```
for an unpushed branch
Re-trigger a failed run with
```
gh run rerun <id>
```
after diagnosing why it failed (don't blindly rerun flaky-looking failures — find the root cause first)
Merge a clean PR (
```
gh pr merge --squash --auto
```
) if the user said yes for that specific PR

Bump

MARKETING_VERSION

CURRENT_PROJECT_VERSION

project.pbxproj

Add a CHANGELOG entry, tag the release with
```
git tag
```
(don't push tag until user confirms)
Drop or pop a stash after showing the diff

读取失败的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
```
标记版本（在用户确认前不要推送标签）
在显示差异后丢弃或应用暂存内容

What requires the user to act

需要用户执行的操作

Print the exact command they should run with a leading

```
! fastlane pilot upload
```
— App Store / TestFlight submission signs the binary; needs them
```
! open Cathier.xcodeproj
```
— anything that needs Xcode archive UI
Anything destructive:
```
git reset --hard
```
,
```
git push --force
```
, deleting branches

打印用户应运行的精确命令，命令前加

：

```
! fastlane pilot upload
```
—— App Store / TestFlight提交需要对二进制文件签名；需用户操作
```
! open Cathier.xcodeproj
```
—— 任何需要Xcode归档UI的操作
任何破坏性操作：
```
git reset --hard
```
、
```
git push --force
```
、删除分支

Common findings → standard fixes

常见问题 → 标准修复方案

Finding	Standard fix
Local branch ahead of main, no PR	Rebase on main, push, `gh pr create`
PR failing CI on same step twice	Read failed log, fix root cause, don't blindly rerun
Unreleased commits + stale TestFlight	Bump build number, tag, write release notes, prompt user to run `fastlane pilot`
Stash >30 days, unclear context	Show `git stash show -p <n>` to user, ask drop/apply
TODOS.md item with no commit	Surface to user — descoped or forgotten? Don't assume
Auto-merged feedback PRs newer than last build	The fix is a new TestFlight build, not more code changes
`fastlane/` untouched but plan says App Store deadline passed	Surface the deadline + last submission date; user decides priority

发现的问题	标准修复方案
本地分支领先main分支，未打开PR	基于main分支变基、推送、使用 `gh pr create` 打开PR
PR在同一步骤连续两次CI失败	读取失败日志，修复根本原因，不要盲目重新运行
存在未发布提交 + TestFlight构建过时	更新构建号、标记版本、编写发布说明，提示用户运行 `fastlane pilot`
暂存内容超过30天，上下文不明确	向用户显示 `git stash show -p <n>` ，询问是否丢弃/应用
TODOS.md中的项无对应提交	告知用户——是范围缩小还是被遗忘？不要假设
自动合并的反馈PR晚于上一次构建	修复方案是生成新的TestFlight构建，而非更多代码变更
`fastlane/` 未修改但计划显示App Store截止日期已过	告知用户截止日期和最后一次提交时间；由用户决定优先级

Red flags — STOP

危险信号 — 立即停止

Thought	Reality
"I'll just fix it and skip the checklist"	No. The user asked specifically for the audit-then-confirm flow.
"The PR looks safe to merge, I'll do it"	Only if they confirmed this PR by name in their reply.
"I'll force-push to clean up history"	Never without explicit per-action confirmation.
"Let me close that stuck PR to tidy up"	Investigate first; the work may be salvageable.
"I'll submit to App Store on their behalf"	Never. Print the `! fastlane …` command and stop.
"The crash report is probably nothing"	Pull the stack and surface it. Let the user decide.
"Plan item is old, must be obsolete"	Ask. Don't delete plan entries.

想法	实际要求
"我直接修复问题，跳过检查清单"	不行。用户明确要求先审计再确认的流程。
"这个PR看起来可以安全合并，我直接合并"	仅当用户在回复中明确确认该PR时才可执行。
"我要强制推送来清理提交历史"	绝不能在未获得明确的逐项确认的情况下执行。
"我关闭那个卡住的PR来整理一下"	先调查；相关工作可能可以挽救。
"我代表用户提交到App Store"	绝不能这么做。打印 `! fastlane …` 命令后停止。
"这份崩溃报告可能没什么问题"	获取堆栈信息并告知用户。由用户决定。
"计划项已过时，肯定废弃了"	询问用户。不要删除计划条目。

Notes specific to this user / Cathier

针对该用户 / Cathier的特殊说明

Default working dir:
```
/Users/jianshuo/code/Cathier
```
. Honor wherever invoked.
Cathier is a SwiftUI iOS app with
```
fastlane/
```
for App Store / TestFlight.
Plan source of truth lives in
```
TODOS.md
```
and
```
APP_STORE_SUBMISSION_GUIDE.md
```
. Read both.
Memory note: in-app feedback →
```
app/claude
```
opens a PR → auto-merge to main. So "why isn't my feedback in the app" usually means the merge happened but no new build was cut. Check TestFlight build date vs PR merge date before investigating the code.
```
gh
```
is authenticated.
```
fastlane
```
is installed (Gemfile present).
DESIGN.md is the visual source of truth; never propose UI fixes that conflict with it without flagging.

默认工作目录：
```
/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修复建议，必须先标记说明。