review
Audit the debt registry, rank survivors by churn × Fowler quadrant, surface a top-N list, then walk paydown on user follow-up. Use when the user asks to review debt, see what to pay down, work through entries, or invokes $review. Stale entries drop with "drop A,B,C".
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- review
- description
- Audit the debt registry, rank survivors by churn × Fowler quadrant, surface a top-N list, then walk paydown on user follow-up. Use when the user asks to review debt, see what to pay down, work through entries, or invokes $review. Stale entries drop with "drop A,B,C".
02 资源文件 1
- 脚本scripts/review.py11.5 KB
03 SKILL.md 正文
review — audit + (on follow-up) walk paydown
Two modes. First turn: print the audit and stop. On a user follow-up ("fix the top one," "walk these," "do A," "pay some down"), apply the rubric below.
First turn: print the audit
Run the bundled review.py (it lives in this skill's scripts/ directory — reference it with the relative path; Codex resolves it against the skill root):
python3 scripts/review.py
Optional: --top N to surface more than the default 3 candidates.
Re-emit the helper's stdout verbatim in a fenced code block. Codex may collapse long bash outputs — if you don't print it yourself, the user might not see it. Copy exactly: no preamble, no summary, no "want me to fix the top one?" The fenced block preserves column alignment.
Then stop. The user picks the next move.
Paydown mode (only on user follow-up)
Work through requested entries one at a time. Confirm before each fix. Never auto-batch. Never auto-commit.
For each entry, read the registry file, the hotspot, and adjacent tests. Apply this rubric:
- Already fixed? If the marker/symptom the entry describes no longer appears in the hotspot file, say so and add the entry's letter to the drop list. Don't re-fix.
- Cold area? Churn=0 since
created:and age >90d → propose deferring. ~20% of files generate ~80% of debt-related rework; don't pay down vanity refactors. - Prudent-deliberate with payoff_trigger not met? Honor the trigger. Skip with a one-line "trigger not met: <quote>."
- Fix candidate? Propose the smallest change that resolves the entry. Improvement, not perfection — don't refactor surrounding code.
When you fix
- Read the repo first. Check the test framework, adjacent tests, the cached feedback commands. Adapt to what exists; don't impose a new style.
- TDD where tests exist. Write a failing test that pins the deferral, then make it pass. Don't weaken or delete existing tests to make a fix pass.
- No tests in this area? Surface that and ask: write one, or fix without?
- Explain why this resolves the entry. Cite the entry's
payoff_triggeror body — don't commit code you can't explain. - Risky fix? Auth, payments, migrations, public APIs, or
ai_authored: true→ run a fresh-context review of the diff before suggesting commit. Fresh-context review catches what the writer's motivated reasoning misses. - Don't commit. Show the diff. The user runs the gates, drops the entry with
drop A, and commits.
Pacing
Aim for 3–10 entries per session — continuous paydown outperforms stop-the-world batches. If the user says "do them all," push back once: unsupervised AI cleanup measurably increases duplicate blocks and short-term churn. If they insist, still one-at-a-time with diffs surfaced.
Speak plainly
The frontmatter uses a research taxonomy (quadrant, category) for ranking and grounding — it is not user-facing vocabulary. When you talk about an entry, describe it in plain words; never say "prudent-inadvertent", "reckless-deliberate", "code_rot", etc. to the user. Use the entry's body and a plain phrase (e.g. "a planned tradeoff", "a shortcut you knew about", "came up later") instead. The review.py output is already translated — match its tone.
Don't
- Don't ask the user to confirm before running
review.py. - Don't paraphrase the helper's stdout. Copy it verbatim into the fenced code block.
- Don't enter paydown mode on the first turn. Stop after the report. Wait for the user's intent.
- Don't auto-commit. Ever.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.