cross-verified-feature-development

Cross-Verified Feature Development

A structured workflow for high-stakes backend features. After implementation, it runs 4 independent verification passes to catch bugs that self-review and standard code review miss — particularly concurrency races, idempotency gaps, and cross-service contract breaks.

Prerequisites · Prerequisites

This skill orchestrates Superpowers sub-skills in the ecosystem to complete the work of each phase.

Install Superpowers (one-time):

claude mcp add --transport http superpowers https://superpowers.anthropic.com/mcp

Sub-skills this skill depends on:

Phase	Skill	Purpose
1	`superpowers:brainstorming`	Requirements analysis → structured spec
2	`superpowers:writing-plans`	spec → executable task list
3	`superpowers:test-driven-development` + `superpowers:subagent-driven-development`	Test-first + each task implemented by an independent subagent
4.1	`superpowers:systematic-debugging`	Structured debugging framework for the self-check phase
5	`superpowers:writing-plans` + `superpowers:subagent-driven-development`	Fix iteration
6	`superpowers:verification-before-completion`	Acceptance: prove each completion criterion with evidence
7	`superpowers:requesting-code-review` → `superpowers:receiving-code-review`	Submit for review → receive and address review feedback
9	`superpowers:finishing-a-development-branch`	Branch wrap-up: merge / PR / cleanup

Works without Superpowers too (fallback):

Phase	Fallback approach
Phase 1	Manually write the spec document, ensuring it includes: problem statement, technical approach, invariants list, failure mode analysis, risk table
Phase 2	Manually break down the task list; each task must have files + line numbers + verification commands
Phase 3	Write failing tests first, then implement task by task (using `subagent-driven-development`), and after each task is complete do a self-review before moving to the next
Phase 4.1	Follow `references/cross-verification-techniques.md` in the 4.1 checklist to self-check manually
Phase 4.2–4.5	Directly use `references/cross-verification-techniques.md` the agent prompt templates to dispatch subagents
Phase 6	Run the verification commands item by item against the spec's Success Criteria; without passing evidence it does not count as complete
Phase 7	Manually go through the PR + code review process; major issues go back to Phase 4/5 for fixing
Phase 9	Manually clean up the branch, update the CHANGELOG, notify downstream

Overview · Overview

This is arigorous feature development methodology with multiple rounds of cross-validation, used when developing critical business features tominimize the probability of production incidents。

Core Insight · Core Insight

A single-perspective review has systematic blind spots. Even the most experienced developers will:

Be "led astray" by their own design thinking
Assume certain field semantics are unique (they may actually be ambiguous)
Assume operations that "should be idempotent" really are idempotent (they are not)
Miss concurrency windows
Forget to update documentation, causing design docs and code to become disconnected

Signals produced from independent perspectives are independent of each other. When N reviewers who know nothing about each other review a feature in turn, the set of bugs foundis close to a union rather than a repetition. So the essence of this workflow is:

Design → Implementation → Multiple rounds of independent cross-validation → Fix → Careful simplification → Documentation sync

Comparison with Standard Workflow · Differences from a standard development workflow

Stage	Standard approach	This workflow
Requirements	Verbal communication / simple PRD	`brainstorming` forms a complete spec
Implementation plan	Planning in the developer's head	`writing-plans` is made explicit as a task list
Implementation	One person writes it all continuously	`subagent-driven-development`, each task independently reviewed
Verification	Self-testing + one code review	4 rounds of independent cross-validation(the core of this skill)
Fix	Change directly	If a problem is found, go through another round of plan + execute
Simplify/optimize	Delete and trim code directly	Verify with skepticism, and bravely roll back when a trap is found
Documentation	Forgotten after implementation	Force backfilling, and record an evolution log

When to Use · Applicable Scenarios

This workflowis worth the cost: features with an estimated implementation effort of ≥ 3 person-days and a high cost of failure.

Typical applicable domains(sorted by "cost of a bug", any one match suggests using it):

Domain	Typical scenario
Money flow / payments	Collection, refunds, settlement, coupon redemption, balance changes
Order / transaction state machine	Order state progression, cancellation, order modification, fulfillment, after-sales
Inventory / stock locations	Deduction, rollback, reservation, cross-warehouse transfer
Permissions / identity / compliance	Authorization, authentication, desensitization, audit trail
Concurrency control	Distributed locks, optimistic locks, CAS, idempotent retries
Cross-service collaboration	Adding cross-microservice interfaces, MQ protocols, asynchronous message pipelines
Core data models	Shared proto / model changes, primary key semantic changes
Data migration / schema	Online DDL, dual-write switchover, backfilling, historical data repair
Configuration/switches	Feature flags, canary rules, configuration changes affecting money or orders

Not applicable：

Pure UI / frontend display adjustments
Pure CRUD with no state machine semantics
One-off data processing scripts
Fixing a small bug
Implementation effort < 1 person-day

Decision heuristic: if you can answer "what is the worst bug this feature could cause?" in one sentence and the answer containsfinancial loss / data corruption / orders stuck / user privilege escalation / production incident, then it is worth going through this workflow.

Decision tree · Decision tree:

Does the feature involve any of the following?
│
├── 💰 Financial transactions, payments, refunds, settlements?      ──→ YES → Use this workflow
├── 🔄 Order / inventory state machines with status transitions?    ──→ YES → Use this workflow
├── 🔒 Distributed locks, concurrency control, idempotent retry?    ──→ YES → Use this workflow
├── 🔗 Cross-service MQ/RPC contracts or shared proto/model change? ──→ YES → Use this workflow
├── 🗄️  Online schema migration or dual-write strategy?             ──→ YES → Use this workflow
└── ⏱️  Estimated effort ≥ 3 person-days?
    └── AND worst-case bug causes: money loss / data corruption /
        stuck orders / privilege escalation / production incident?  ──→ YES → Use this workflow

None of the above?  ──→  Standard workflow is fine ✓

9-Phase Workflow · Complete 9-phase workflow

① 需求/设计        → superpowers:brainstorming
①.5 架构决策评审   → ADR（高风险特性必做）
② 实施计划        → superpowers:writing-plans（含部署策略）
③ 实施           → superpowers:test-driven-development + superpowers:subagent-driven-development
④ 🔥 多轮交叉验证  ← 本 skill 的核心创新
⑤ 迭代修复        → writing-plans round 2 + subagent-driven-development（含回归保护）
⑥ ✅ 验收          → superpowers:verification-before-completion
                      ↩ 验收不通过 → 回 Phase ② 重新规划
⑦ 👁 代码评审       → superpowers:requesting-code-review → receiving-code-review
                      ↩ 重大问题 → 回 Phase ④/⑤ 调试修复
⑧ 谨慎简化        → 带怀疑的优化
⑨ 文档同步/收尾   → 回填 evolution log + superpowers:finishing-a-development-branch

Phase 1: Requirements & Design · Requirements/Design

Goal: turn vague business needs into astructured design document。

How to do it: call superpowers:brainstorming. Produce a spec, usually saved in docs/superpowers/specs/YYYY-MM-DD-<feature>-design.md。

Key output checkpoints: the spec must include

Problem statement and business boundaries
Technical approach anddecision points(every decision must have an argument for "why not choose B")
Invariant list (hard business-layer constraints)
Failure mode analysis (at least 4 crash/failure scenarios)
Risk table
Effort estimation

Anti-patterns: Skip brainstorming and go straight to implementation. → The later verification phase will repeatedly fail.

✅ Exit Criteria — Phase 1 completion standards:

Spec document has been created (docs/superpowers/specs/YYYY-MM-DD-<feature>-design.md）
Spec includes: problem statement, technical approach, invariants list, ≥4 failure modes, risk table, effort estimate
Each decision point has an argument for "why the alternative was not chosen"
Stakeholders have confirmed the requirement scope

Phase 1.5: Architecture Decision Review · Architecture Decision Review (required for high-risk features)

Trigger conditions: Required when the design involves any of the following—distributed lock approach, idempotency mechanism design, state machine transition diagram, cross-service data consistency approach, online schema migration strategy, shared proto/model changes.

Goal: Before touching code, explicitly verify thekey architecture-level decisionsonce. The cost of discovering an error during the design phase is discussion cost; the cost of discovering in Phase 4 that the design itself is wrong is overturning + rewriting.

How to do it: For each key technical decision in the spec, write an Architecture Decision Record (ADR), answering:

What was chosen: The specific approach (e.g., use Redis + DB CAS double insurance to implement idempotency)
What the alternatives were, and why they were not chosen(each alternative must have an argument; you cannot just say "not suitable")
Failure modes of the chosen approach: List the 3 most likely failure scenarios (do not assume it will not fail)
Can the invariants be satisfied at the design level: Check the Phase 1 invariants list item by item, and confirm the design has corresponding guarantee mechanisms

Typical output: 1-3 ADRs, appended to the end of the spec document (not a separate file, to avoid fragmentation).

When it can be skipped: It can be skipped when the feature is a purely new interface, has no concurrency control requirements, has no state machine, and has no cross-service data writes.

Anti-pattern: Writing the ADR as "we chose X" and then only writing the advantages of X. The value of an ADR lies inrecording why the alternatives were not chosen, which is the information future maintainers need most.

✅ Exit Criteria — Phase 1.5 completion standards:

Each key technical decision (distributed lock / idempotency mechanism / state machine / consistency approach / schema migration) has a corresponding ADR
Each ADR answers: what was chosen, why the alternatives were not chosen, failure modes of the chosen approach
All invariants from Phase 1 have been confirmed to have corresponding guarantee mechanisms at the architecture level

Phase 2: Implementation Plan · Implementation Plan

Goal: Break the spec intoa task list that can be executed independently and verified independently。

How to do it: Call superpowers:writing-plans. Save to docs/superpowers/plans/YYYY-MM-DD-<feature>.md。

Key output checkpoints：

Each task has explicit files + line numbers + code examples
Dependencies are clear
Verification method is specific (build / lint / test commands)
commit message template
TDD structure (write failing tests first, then implement)
Release strategy: full rollout / feature flag / canary percentage / dual-write switch window (choose one, but it must be explicit)
Rollback criteria: Which metric anomalies trigger a rollback? Who decides? (This cannot be left until launch time)
New monitoring/alerts: After this feature goes live, which metrics and alerts need to be added?
Ops SOP changes: What special operations do DBA/SRE need to perform? (if any)

Anti-patterns: Writing "TODO", "handle later", or "similar to Task N" in a task. → Execution gets stuck or generates inconsistent code. Leaving the launch strategy blank → No feature flag hook during Phase 3 implementation → Temporarily modifying code to launch.

✅ Exit Criteria — Phase 2 completion criteria:

Every task has an explicit file path + line number + code example
Every task has a concrete verification command (make build / make test / lint, etc.)
TDD structure: failing tests are written into the plan before implementation
Launch strategy is explicit (full rollout / feature flag / canary / dual-write switch)
Rollback criteria are defined: which metrics trigger a rollback, who decides
New monitoring/alerts have been included in the plan

Phase 3: Implementation · Implementation

Goal: Tests first, implement task by task according to the plan, with an independent review for each task.

How to do it：

First call superpowers:test-driven-development: For each task,write the failing test first, confirm the test fails, and then write the implementation.
Then call superpowers:subagent-driven-development: Drive implementation according to the plan produced in Phase 2. For each task:
- Dispatch implementer subagent（fresh context）
- Implementer self-review + commit
- Dispatch spec compliance reviewer (verify whether the required things were built)
- Dispatch code quality reviewer (verify code quality)
- If any reviewer finds an issue → implementer fixes it → re-review
- All pass → next task

Key mindset：A fresh subagent for each independent task compared with writing everything continuously in one large contextis less error-prone, because there is no accumulated bias. Writing the failing test first can expose design ambiguities before implementation.

Anti-patterns：

Skipping writing tests and implementing directly to save effort → During Phase 4 verification, insufficient test coverage is discovered, and the cost is higher
Combining multiple tasks and giving them to one subagent to finish → Verbose context → Key constraints are forgotten

✅ Exit Criteria — Phase 3 completion criteria:

All tasks in the Plan are marked complete and have corresponding commit SHAs
Each task has a failing test written before implementation (tests go red first, then green)
Build passes:make build(or the project-equivalent command)
Tests pass:make test(or the project-equivalent command)
Each task has undergone spec compliance review + code quality review
No leftover TODO / stub on the critical path

Phase 4: 🔥 Cross-Verification Rounds · Multiple rounds of cross-verification (the core of this skill)

After Phase 3 ends, the codeon the surfacealready works. Butbeing able to compile + pass unit tests ≠ production-ready。

This phase uses 4 independent perspectives Review the code in turn; the signals provided by each perspective are independent of one another.For detailed steps, see references/cross-verification-techniques.md。

4.1 Systematic Debugging (internal self-check)

Perspective: Using superpowers:systematic-debugging as the framework, scan your own code from the angle of "if a bug occurred at this point, what would it be".

When to stop: No new critical issues are found, and all claimed invariants have been checked.

Typical output: 1-3 pre-existing bugs found (not introduced by this change but discovered along the way).

4.2 Cold-Context Code Review (external independent review) ⭐

This is the highest-value verification in this workflow. Start a fresh reviewer agent,do not give it the design document, and give it only:

A one-sentence goal for the Feature
Branch name + repository path
A "find bugs" prompt

Key constraint：DO NOT read the design document. This sentence must be written into the agent prompt.

Why it is effective: The design document represents "what the author believes the system should do". Showing the document to the reviewer makes it infected bythe author's blind spots. A cold-context reviewer only looks at what the code actually does, and can instead discover flaws in the design itself.

Typical output: 5-15 critical / high severity concurrency / consistency / idempotency vulnerabilities.

4.3 Behavior-Preservation Diff (master vs feature behavior differences)

Perspective: Enumerate the master branch'sall side effects(DB writes, MQ publishes, RPC calls, cache writes, log alerts), compare them item by item with the feature branch, and answer "whether the original business logic has been changed".

When it is needed: It must be done when the feature includes "modifications to an existing flow" rather than merely "adding a new feature".

Typical output: 2-5 changes in the order/semantics of side effects are found, and each one needs to be confirmed as expected.

4.4 Cross-Repo Impact Scan (cross-repository impact)

Perspective: Identify whether this feature affectsother repositories' code behavior, and whether corresponding changes are needed.

Typical inspection dimensions：

Whether MQ consumers need to change their deduplication logic (the feature may make duplicate messages more frequent)
Whether RPC callers need to handle new error codes
Whether readers/writers of shared DB tables need to adapt to new states
Whether shared proto / model is backward compatible

Typical output: Identify 0-3 impact points in other repositories; in most cases it is "no change needed" butneeds confirmation。

4.5 Business Invariant Matrix (mandatory for funds/state machine/inventory/permissions scenarios)

Perspective: List thebusiness-layer hard constraintsthat the feature must preserve (for example, "a business document can produce at most one funds change", "retry_count increases monotonically", "state can only move forward, not backward"), and verify item by item that the code preserves them on all paths.

When to do it: When any of the following is hit, it ismandatory, on par with 4.2 (not optional):

Funds flow / payment / refund / balance changes
Order / inventory state machine (with explicit state transition constraints)
Inventory deduction / reservation / return
Permission granting / authorization chain

Other scenarios (pure new interfaces, no state machine semantics) can be skipped.

✅ Exit Criteria — Phase 4 completion criteria:

4.1 Complete: concurrency points / failure modes / idempotency / state machine / boundaries all checked; all findings recorded
4.2 Complete: cold-context reviewer did not receive the design document; all Critical/High issues recorded
4.3 Complete (if applicable): all side effects labeled ✅/🟢/🟡/🟠/🔴/🆕/❌
4.4 Complete (if applicable): all cross-repository impacts confirmed or flagged
4.5 Complete (if applicable): all invariants verified one by one
All findings summarized into an issue table (source / severity / location / fix direction), ready to hand off to Phase 5

Phase 5: Fix Iteration · Iterative fixes

Goal: fix the issues found in Phase 4 until clean.

How to do it: summarize all discovered issues into a new plan (docs/superpowers/plans/YYYY-MM-DD-<feature>-review-fixes.md), then go through writing-plans + subagent-driven-developmentagain (including TDD: write a regression test first for each fix).

Key principles：

Batch by severity：Critical → High → Medium → Low
Each fix in an independent commit, to facilitate rollback
Each Critical fix must have corresponding automated test coverage—a fix without tests does not count as complete, because regression is extremely likely in the next iteration
After all fixes are merged, the 4.2 cold-context review must be rerun(cannot be skipped)—the fix itself may introduce new bugs; the reviewer can focus attention on the diff and does not need to re-review the entire codebase
If rerunning 4.2 reveals more than 2 new High-severity issues, stop and assess: continue patching, or reconsider the design approach

Typical magnitude: cold review finds 10+ issues → fix plan of 10-15 tasks → 3-5 person-days.

✅ Exit Criteria — Phase 5 completion criteria:

All Critical issues fixed, each fix has corresponding automated tests
All High issues fixed, or have an explicit accepted-risk statement (including approver)
Rerun 4.2 cold-context review: newly discovered High-severity issues < 2
Each fix has an independent commit (to facilitate individual rollback)
Regression test suite all passes

Phase 6: Verification-Before-Completion · Acceptance

Goal: usereproducible execution evidenceto prove each completion criterion has been met—"I think it's fine" does not count as complete.

How to do it: call superpowers:verification-before-completion. The framework requires:

Against the spec's Success Criteria and the Phase 2 plan's Exit Criteria, collect item by itemscreenshots/logs of actual command outputas evidence
Each criterion must have the actual run result of the corresponding command, rather than asserting "completed"
If any Critical criterion is found not to pass → must not proceed to Phase 7

⚠️ Feedback Loop:

If acceptance reveals that the standard simply cannot be met under the current design (not a bug, but a deviation in the design itself),go back to Phase 2(writing-plans) and re-plan; do not keep patching. Design problems exposed during the acceptance phase cost less than during the review phase, and far less than in production.

✅ Exit Criteria — Phase 6 completion standards:

Every Success Criterion in the Spec has runtime evidence item by item (command + output, not verbal assertions)
make build + make test all pass, logs have been saved
No leftover Critical/High unresolved issues
If a design-level deviation is found: have returned to Phase 2 to re-plan, and the current Phase 6 is paused

Phase 7: Code Review

Goal: throughan independent reviewer's external perspectivecatch the implementer's blind spots, and fix major issues before merge.

How to do it：

Call superpowers:requesting-code-review: prepare the review request (diff scope, background summary, known risks, points needing attention) and submit it
Call superpowers:receiving-code-review: handle reviewer feedback in a structured way—classify item by item (accept / request-clarification / push-back with reason); do not accept everything by default

Feedback Loop:

If the review findsmajor issues(logic errors / concurrency races / idempotency loopholes / design-level mismatch),go back to Phase 4/5(systematic-debugging + iterative fixing); do not patch in place within the review comments. After returning, Phase 6 acceptance must be run again.

"Major" determination heuristic: if this problem were only discovered in production, would it trigger an incident? If yes, count it as major.

✅ Exit Criteria — Phase 7 completion standards:

All Critical/High review comments have been handled (fixed or with a documented reason for acceptance)
Major issues have been fixed by going back to Phase 4/5, and have passed Phase 6 acceptance again
Medium/Low comments have been dispositioned (accept / defer with reason)
The Reviewer confirms there are no new blocking issues

Phase 8: Careful Simplification

Trigger point: after Phase 5 ends, sometimes you find that the code "seems to have redundancy" or "looks like it can be simplified."

⚠️ Core discipline：Before simplifying, all hidden assumptions must be verified. See references/anti-patterns.md the "Simplification Trap" section.

The traps most easily fallen into：

Polysemous field trap: assuming a field stores only one semantics, when in fact another branch stores something else.Simplifying away some "seemingly redundant" storage/cache, resulting in data corruption。
Re-derivation trap: assuming some value can be reconstructed from DB state, when in fact some values are snapshots of local variables and have no deterministic DB source.
Overconfidence trap: the code under review has passed stress testing and all verification, and the developer has the feeling that "I understand this code very well." This is exactly when judgment errors are most likely.

The correct approach：

Before simplifyingexplicitly listthe code you are about to removeWhydoes it exist
For each reason, findcode evidenceproving it "can really be removed"
What cannot be proven,keep
After simplificationrun cold-context review again(fresh perspective) to confirm there is no regression

If things go wrong: decisively git revert, write the lesson into the evolution log, and do not try to "simplify one more time".

✅ Exit Criteria — Phase 8 (if simplification was done):

anti-patterns.md All items in the Simplification Checklist are checked (with code evidence, not "it feels okay")
After simplification, a new round of cold-context review was run, with no new High-severity issues
If simplification failed and was rolled back: the lesson has been written into the evolution log

Phase 9: Doc Sync & Branch Finish · Documentation sync/wrap-up

Goal: backfill thefinal code state into the original design document, then finish the branch cleanly.

Why it matters：

The fixes in Phase 5 will makethe code deviate from the original design; if not synced, the document will mislead the next maintainer
Behind every deviation there is adecision rationale, and these rationales are valuable knowledge assets that cannot be found in the code alone

How to do it: see references/doc-sync-playbook.md. Core principles:

Do not completely rewrite the spec; preserve the original design intent
At deviation pointsmark "original design vs actual implementation"
Append at the end of the document Implementation Evolution Log section, recording Phase 1/2/3... in chronological order
In the Plan document, mark each task with the actual commit SHA + deviation points
Failed simplification attempts (Phase 6 rollback)must be recorded; lessons are more valuable than successes

Do not：

Commit only code, not documentation updates
Assume "code is documentation" by default—half a year later no one can reverse-engineer the decisions from the code
Delete original design content "because it is inconsistent with reality"—that is history, and it is a lesson

Wrap-up: after documentation sync is complete, call superpowers:finishing-a-development-branch; it will guide you to choose: merge / create PR / cleanup stale branches, and deliver after confirming CI is all green.

✅ Exit Criteria — Phase 9 completion criteria:

Every place in the Spec document that deviates from the original design has been marked > ⚠️ 原设计 vs 实际实现
An Implementation Evolution Log has been appended to the end of the Spec (recording key decisions from Phase 1→9 in chronological order)
Failed simplification attempts (if any) have been recorded in the evolution log
Each task in the Plan document has the actual commit SHA + deviation point annotation
Downstream teams have received notifications of interface / protocol / MQ changes (if any)
superpowers:finishing-a-development-branch Complete: branch merge / PR creation / CI all green

Superpowers Integration · Collaboration relationship with the Superpowers ecosystem

This skill does not reinvent the wheel, it only orchestrates:

Phase	Skill used
1	`superpowers:brainstorming`
2	`superpowers:writing-plans`
3	`superpowers:test-driven-development` + `superpowers:subagent-driven-development`
4.1	`superpowers:systematic-debugging`
4.2-4.5	Autonomously dispatch agent (this skill provides the prompt template, see `references/cross-verification-techniques.md`）
5	`superpowers:writing-plans` + `superpowers:subagent-driven-development`
6	`superpowers:verification-before-completion`(Acceptance failed → return to Phase 2)
7	`superpowers:requesting-code-review` → `superpowers:receiving-code-review`(Major issue → return to Phase 4/5)
8	Autonomous execution (with `anti-patterns.md` warning)
9	Autonomous execution (with `doc-sync-playbook.md`）+ `superpowers:finishing-a-development-branch`

Getting Started · Start this workflow

Trigger Modes · Two trigger methods

A. Explicit user trigger(mandatory): the user says /cross-verified-workflow <feature 需求>, "develop in cross-verification mode", "follow the rigorous workflow", "use the cross-verified workflow", etc.

B. Proactively identify and suggest: when the user's task description matches any domain in the "Applicable Scenarios" table (money flows, order state machines, concurrency control, data migration, etc.), or the user mentions keywords such as "refactor core X / overhaul payments / idempotency / distributed locks / new cross-service interfaces",even if the user did not explicitly ask for it, you should proactively propose:

I noticed this task involves <matched domain>, which is a scenario with high bug cost. I suggest following a more rigorous cross-verified workflow (brainstorm → plan → implement → multiple rounds of cross-verification → fix → documentation backfill). It will take about 40-50% more time than the usual approach, but it can raise the critical bug detection rate from ~40% to ~95%. Would you like to follow this process?

Or if you think the cost is too high, we can also follow the regular process.

Do not force people into the workflow—explain the value and the cost, and let the user choose. Butdo not silently skip itand let the user run naked on high-risk changes.

Startup Steps · Startup steps

Step one: confirm the user's intent. If the requirements are not yet clear enough, first ask the user to clarify
Step two: assess whether it is truly suitable (refer to the "Applicable Scenarios" section)—if not, suggest a simpler process
Step three: if suitable, call Phase 1 (superpowers:brainstorming) to begin

Progress Tracking · Progress tracking

After each Phase is completed, clearly mark the progress:

✅ Phase 1   (Brainstorming) → docs/superpowers/specs/<file>.md
✅ Phase 1.5 (Arch Pre-flight) → ADR 追加到 spec（或 N/A）
✅ Phase 2   (Planning) → docs/superpowers/plans/<file>.md
⏳ Phase 3   (TDD + Implementation) → 进行中 (5/12 tasks done)
⬜ Phase 4a  (Systematic Debugging)
⬜ Phase 4b  (Cold-Context Review)
⬜ Phase 4c  (Diff Audit + Cross-Repo + Invariant，并行)
⬜ Phase 5   (Fix iteration)
⬜ Phase 6   (Verification-Before-Completion)  ← 验收不通过 → 回 Phase 2
⬜ Phase 7   (Code Review: Requesting → Receiving)  ← 重大问题 → 回 Phase 4/5
⬜ Phase 8   (Careful simplification)
⬜ Phase 9   (Doc sync + Finishing-A-Development-Branch)

Common Rationalizations · Common self-rationalizations

These are the thoughts that mean stop — you're about to skip something important. When the following thoughts appear, stop immediately—you are finding reasons to skip key steps.

Rationalization · Rationalization excuse	Reality · Reality
"The code passed all tests, so cold-context review can be skipped"	Tests verify "whether the expected behavior was implemented"; they do not verify "whether the design itself is correct." Cold-context review specifically looks fordesign-levelflaws—these are exactly the flaws the author is least able to see, because the author assumes their own design assumptions
"This change is small; the full process costs too much"	Historically, the most expensive bugs have almost all come from changes that "look small." Small change ≠ small risk; small changes often touch the boundary conditions of core paths, and these conditions are most easily overlooked during review
"I am very familiar with this codebase, so I do not need to self-review"	Familiarity creates assumption blind spots. The value of Phase 4.1is precisely because you are very familiar——You can more accurately list all implicit assumptions, then challenge them one by one. The most dangerous moment is the moment you are most confident (see anti-patterns Trap 3)
"Team code review will catch the problems"	In standard code review, the reviewer and the author share the same context and assumptions. The core constraint of cold-context review isdo not show the design document to the reviewer——the set of bugs found barely overlaps with code review
"This RPC interface looks idempotent"	There is an actual code gap between "looks" and "is." Phase 4.4 requires that for each retry path's RPC read the underlying implementation, not look at the interface signature. Case 4 is the cost of trusting interface signatures
"Phase 7 document sync can wait until I have time"	Time will never come. The fixes in Phase 5 have already made the code deviate from the original design; not syncing the documents is planting a landmine for the next maintainer—he will write code according to the wrong documents and step into a variant of the same pit (see Case 6)
"4 rounds of cross-validation is too many; picking 1-2 rounds is enough"	The bug signals produced by 4 rounds of validationare closer to a union rather than duplicates. Doing only 4.1 will not find design flaws; doing only 4.2 will not find cross-repository impacts; skipping any round is a systemic blind spot, not a time saving
"The fix is done, no need to rerun cold-context review"	The fix itself may introduce new bugs. To the reviewer, the fixed code is entirely new and can provide a completely independent signal. Phase 5 explicitly requires: after all fixes are merged in,rerun 4.2 at least once
"Skip Phase 6 acceptance; I know the functionality is good"	Knowing and having evidence are two different things. The value of Phase 6 is not "finding bugs," butgenerating reproducible completion evidence. Without evidence, the Phase 7 reviewer also cannot work effectively, and review degenerates into guessing
"The review comments are minor, so I can just fix them in place without going back to Phase 4/5"	Patching in place skips the TDD process (no failing test written first) and also skips the multi-round cross-validation of Phase 4. The more urgent the fix, the easier it is to introduce new bugs. Following the loop costs only half a day; skipping it could be an incident
"Failing acceptance is just a small problem; patching it a bit is enough, no need to go back to Phase 2"	The loop trigger condition of Phase 6 is "design deviation," not "there is a bug." If it is a bug, fixing it within Phase 6 is enough. If it is a design that cannot meet the Success Criteria, continuing to patch will only push technical debt into production

Reference Files · Key Reference Files

This skill body stays concise, with details in references:

File	When to read
`references/cross-verification-techniques.md`	Must-read at the start of Phase 4, containing the agent prompt template for each type of validation
`references/anti-patterns.md`	Must-read before Phase 6 (simplified) to avoid pitfalls
`references/doc-sync-playbook.md`	Must-read at the start of Phase 7, for standardized document backfilling
`references/case-studies.md`	Optional. A collection of real-world pitfall cases from actual projects, helping to understand why each discipline exists

FAQ · Frequently Asked Questions

Q: Must every Phase be done?

A: Phase 1-3 + 6 + 7 + 9 are mandatory. For Phase 4, do at least 4.1 and 4.2. Phase 5 and 8 are as needed. 4.3-4.5 depend on feature complexity.

Q: Do the 4 rounds of verification in Phase 4 need to be done in order?

A: 4.1 is recommended first (self-check cost is low), with 4.2 (cold-context) immediately after. 4.3-4.5 can bedispatched in parallel(independent subagents), which can significantly save time.

Q: When a new batch of issues is discovered, should Phase 4 be redone from scratch?

A：After fixing, only the changed parts need to be re-verified with focus. There is no need to run all 4 rounds completely for every change. However, before the final merge, it is recommended to run 4.2 (cold-context) at least once more to confirm that no new issues have been introduced.

Q: Will this workflow be too slow?

A: A medium-complexity feature (~5 person-days of implementation) takes about 7-10 person-daysin total with this workflow. What the extra 40-50% of time buys is:the Critical bug discovery rate increases from a typical 40% to 95%. Phase 6 acceptance and Phase 7 code review take only half a day in most high-quality implementations—loops are triggered only when there are systemic problems in the design or implementation, and that is exactly the situation most worth spending time on. For critical features, this ROI is an overwhelmingly positive return.

Q: Can this workflow be used for frontend/UI features?

A: Not recommended. UI changes that are purely presentational, purely CRUD, and have no state-machine semantics are not worth this cost. Only consider it when the frontend changes involve scenarios such aspayment flows, order confirmation, permission authorization, critical data submission.