xxxx2l/design-to-implement

Solution Design & Implementation Workflow

Core Philosophy

First clarify thoroughly, then start writing code. This workflow strictly separates "thinking" from "doing":

• Discussion Phase: Only dialogue, no code writing. All conclusions are recorded in the Communication Document.
• Design Phase: Solidify consensus into a Design Document — the single source of truth.
• Implementation Phase: Generate an Implementation Document based on the Design Document, and execute step by step.

Code is never touched until a conclusion is reached and the user explicitly says "proceed with implementation." If there are still questions, continue discussing until both parties are satisfied.

Document Directory Structure

Fixed location under the project root at docs/design/, each task gets its own subfolder:

project_root/
└── docs/design/
    ├── README.md              ← Global task overview (entry point for multiple tasks, read first)
    ├── 01-user-auth-module/
    │   ├── 00-task-status.md      ← Cross-context memory anchor
    │   ├── 01-communication.md
    │   ├── 02-design.md           ← Includes acceptance criteria
    │   ├── 03-implementation.md
    │   └── 04-test.md             ← Test cases (generated during implementation planning)
    └── 02-payment-refactor/
        └── ...

Naming rules:

• Task folders: Global incrementing two-digit index + task name, e.g., 01-user-auth-module, 02-payment-refactor. Indices are consecutive across tasks to maintain creation order.
• Documents within a task: Fixed phase prefixes: 00-task-status / 01-communication / 02-design / 03-implementation / 04-test. Fixed prefixes let you immediately locate the same type of document in any task.

Determining the index when first entering a task: Look at the highest existing folder number under docs/design/, and add 1 for the new task. If the directory doesn't exist, start from 01.

First Step in Every New Conversation (Multi-Context Memory Mechanism)

This workflow may span multiple conversation contexts. To avoid re-reading code extensively or losing memory on each new conversation, follow this order to restore context:

1. Read docs/design/README.md — Global task overview; identify which tasks exist and their current phase. If the user specified a task, jump directly to it.
2. Read 00-task-status.md — Memory anchor for the current task; confirm the next action.
3. Read the document corresponding to the current phase (e.g., read 02-design.md during the design phase, 03-implementation.md during the implementation phase).
4. Only read code when necessary for verification, not as the first means of restoring context.

00-task-status.md must maintain: a one-sentence task summary, current phase, key decision summary, to-dos and questions, document index, context switch log, change log (covering both modifications and rollbacks — see "Changes During Implementation" below).

The Four Phases of the Workflow and Corresponding Documents

Phase 1: Discussion (Output → Communication Document)

Trigger: The user proposes a new requirement, feature, module, or has questions about an existing plan.

Behavioral constraints:

• This phase is discussion only; do not write any business code.
• Append every meaningful exchange (key decisions, rejected alternatives, consensus reached) to 01-communication.md.
• Track unresolved questions: Maintain a list of "Currently Unresolved Questions" at the top of 01-communication.md. Update this list before each discussion ends — which questions remain open, which are new, which have been resolved. The direct criterion for moving to the Design phase is whether this list is empty. This makes the convergence process visible rather than relying on a feeling that "discussion is about done."
• Discussions may be multi-round and span multiple conversations.
• When the user expresses "let's proceed," "that's settled," or "start designing," and the unresolved questions list is empty, move to Phase 2.

When to continue discussing instead of advancing: As long as there are unresolved design questions, technical choice disagreements, or unclear boundaries, keep refining in Phase 1. It's better to ask one more round than to move into design with vague assumptions.

Phase 2: Design (Output → Design Document)

Trigger: Discussion has reached consensus, the unresolved questions list is clear, and the user agrees to finalize the plan.

Behavioral constraints:

• Organize the conclusions from the communication into a structured 02-design.md. The design document is the single source of truth.
• The design document must be as complete as possible: When delivered, it must be a definite, executable plan — no "TBD" or "we'll figure it out during implementation." Completeness is ensured by two things: thorough communication to resolve all questions, and reading existing code to confirm facts that depend on the current implementation (interface shapes, table structures, invocation patterns, etc.). "Only discuss, no code" in the design phase refers to business code; reading existing code to confirm current state for design purposes is design research and does not violate the constraint. Spend more time in the design phase to polish thoroughly; do not enter implementation with any gaps — any gap will result in rework or deviation.
• Acceptance criteria are part of the design: In addition to "what to do" and "why," the design document must specify how to verify satisfaction — i.e., abstract acceptance criteria (at the rule level, e.g., "High-risk keywords must be blocked; the article must not be persisted"). Acceptance criteria define the requirement boundary and are the final link in design completeness; a design document without acceptance criteria lacks an objective definition of "done." Specific test cases (instance level) are not written in the design document but in 04-test.md, generated during the implementation planning phase by concretizing the acceptance criteria into cases.
• Design change log: Maintain a "Design Change Log" block in the design document. Record each significant change (timestamp, what changed, why). It complements 01-communication.md — the communication document is a running log, the design document records conclusions, and the change log captures the evolution of the conclusions. This makes the inviolable rule "change the design document, not the implementation document" truly actionable without losing history.
• After the design document is complete, update 00-task-status.md to mark "Design complete, awaiting implementation," and synchronously update the task phase in docs/design/README.md.

Phase 3: Implementation Planning (Output → Implementation Document)

Trigger: The design document is finalized.

Behavioral constraints:

• Based on the design document, generate 03-implementation.md, breaking the plan into executable, checkable steps.
• Simultaneously, concretize the design document's "Acceptance Criteria" into specific test cases and generate 04-test.md: Cases are instantiations of acceptance criteria (e.g., acceptance criterion "High-risk keywords must be blocked" → case "Input text containing a high-risk keyword, expect return 40901, article not persisted"). Cases are organized into four layers: Functional (T-F), Exception (T-EX), Regression (T-R), and API (T-API), numbered as T-{type}-{two-digit index}, template at assets/test.md.
• The implementation document describes "how to do it," the test document describes "what to test and expected results," and the design document describes "what to do and why." The three have distinct responsibilities; do not copy design details into the implementation document, and do not sneak plan changes into the implementation document.
• The implementation document is a pure step decomposition; each step simply "implements a part of the design document" and does not carry any responsibility for "filling in missing design." If, while breaking down steps, you find a step that requires first "confirming the interface shape," "rewriting the design," or "deciding on a field" before execution, it means the design phase was incomplete — go back to Phase 2 to complete the design, not insert a "design-patch" step in the implementation document. In short: The implementation document should never contain any action that involves "reading code to determine the plan," only actions that "implement a determined plan."
• Test actions in the implementation document should only reference test case IDs, not repeat case content. After each step, to verify, write "Verify against case T-XX-XX"; cases themselves are centralized in 04-test.md.
• Implementation steps are divided into major steps and minor steps, both with independent completion markers.
• After the implementation document is complete, update 00-task-status.md to mark "Awaiting implementation."

Phase 4: Implementation (Execute Steps from Implementation Document)

Trigger: The user says "start implementing," "let's do it," or "follow the document."

Behavioral constraints:

• Strictly follow the steps in 03-implementation.md. After each step, update the document with a completion marker and a brief result note.
• After each step, verify against the test cases referenced in 04-test.md for that step; if a case fails, the step is not considered complete — analyze the root cause (is it an implementation bug, or is the design/case itself problematic? The latter triggers the modification/rollback mechanism). After all steps are complete, run the regression case set (T-R).
• If anything deviates from the design document, stop: First update 02-design.md (including the change log), then synchronously revise 03-implementation.md and 04-test.md (cases change with the plan), then continue. Never deviate from the plan as you go.
• All design deficiencies, new constraints, or API changes discovered during implementation must be written back into the "Design Change Log" block of 02-design.md to keep the design document up to date.
• Every phase switch and every significant milestone must update 00-task-status.md and docs/design/README.md.

Changes During Implementation: Modification Mechanism vs. Rollback Mechanism

The workflow nominally follows Discussion → Design → Implementation Planning → Implementation, but it is expected, not exceptional, to discover deviations between the plan and reality/requirements during implementation — even the most complete design cannot 100% foresee implementation details.

Deviations fall into two fundamentally different categories that must be strictly distinguished and handled by their respective processes:

	Modification	Rollback
Nature	The plan is roughly correct, but has gaps/omissions to fill	This part of the plan is fundamentally wrong and needs to be scrapped
Main plan	Untouched	Scrapped
Completed artifacts	Not invalidated	Partially invalidated
Frequency	Normal	Rare
Typical scenarios	Missing fields, missing branches, missing dictionary values, overlooking a new requirement point	Wrong direction, core assumption invalid, doesn't match actual business

First determine which category it belongs to (judgment responsibility is explained under each mechanism), then follow the corresponding process. When uncertain, lean toward treating it as a "modification" and confirm with the user; only follow "rollback" when it is clearly a fundamental error.

Modification Mechanism (Normal, Lightweight, Incremental)

Three conditions for judgment (all must be true to classify as modification):

1. The main plan direction is correct
2. No completed artifacts need to be invalidated
3. It is merely a supplement/tweak (adding a field, a branch, a dictionary value, a missed requirement point, etc.)

Process (strict order, not to be reversed):

1. Stop current implementation
2. Update the design document first: Supplement content in the relevant section of the design document and add a line to the design change log
3. Wait for user confirmation of this modification (cannot decide or implement on your own)
4. After user confirms, synchronously revise the implementation document
5. Then continue implementation

Key Principle: Update design first, then implement — order cannot be reversed. Prohibited: "implement first, then backfill the design document" — that would degrade the design document from a source of truth to a post-hoc record. Even adding a single field must follow this process.

Rollback Mechanism (Rare, Heavyweight, Scrapping)

Three conditions for judgment (all must be true to classify as rollback):

1. The main plan direction is problematic
2. Completed artifacts need to be invalidated
3. Re-discussion/re-design is needed

Judgment responsibility: The final decision on rollback rests with the user. When the AI suspects a fundamental problem, it can only suggest a possible rollback and explain the reasoning; the AI cannot decide on rollback itself.

Process:

1. Stop current implementation
2. AI suggests a possible rollback, explaining the rationale (which part of the direction is wrong, why it doesn't hold)
3. Wait for the user's final judgment on whether to roll back
4. After the user confirms the rollback, log one line in 00-task-status.md: from Phase X rolled back to Phase Y, reason, which artifacts are invalidated
5. Return to the Discussion/Design phase to realign
6. New plans generated are documented according to the original workflow: new questions into the unresolved questions list of 01-communication.md; plan changes into 02-design.md with an added change log entry
7. Synchronously revise 03-implementation.md

Two Inviolable Rules Common to Both Mechanisms

1. Plan changes always modify the design document, never the implementation document directly
2. Update design first, then implement — order cannot be reversed (never implement and backfill later)
3. Any change must leave a trace in the task status document (modifications go into the design change log; rollbacks additionally have a rollback record)
4. User confirmation is a mandatory checkpoint for all changes (modifications require confirmation of the plan supplement; rollbacks require confirmation of the judgment itself)

Mindset: Deviations are not scary; what's scary is forging ahead with deviations or quietly deviating from the plan. Make "modifications" lightweight and low-friction (the normal case should flow smoothly), make "rollbacks" deliberate (scrapping requires user approval), and standardize traceability for both — this minimizes rework cost.

Step Marking Convention for Implementation Documents

Implementation steps are divided into major and minor steps, both with independent completion markers. Major steps are block-marked with headings and a progress count; minor steps use four-state checkboxes.

Four-state markers:

- [ ]  Not started
- [~] In progress
- [x] Completed
- [!] Blocked (reason noted afterwards)

Organization example:

### 1. Database Layer ✅ 1/3
- [x] 1.1 Create users table (including migration script)
- [~] 1.2 Create indexes
- [ ] 1.3 Write seed data

### 2. API Layer ⬜ 0/2
- [ ] 2.1 Implement POST /api/users
- [ ] 2.2 Integrate authentication middleware

Major step state symbols:

• ⬜ Not started (0/N complete)
• 🌗 In progress (partially complete)
• ✅ Complete (N/N)

Progress count format is uniformly completed/total, placed at the end of the major step heading. This allows seeing both overall progress and pinpointing which minor step is blocking.

Special Handling for Backend Projects

If the current project is a pure backend project (no frontend code, or a separate backend repository in a frontend-backend separation):

• The design document and implementation document only cover backend content, with no frontend implementation details.
• Any new API or change to an existing API (URL, method, request parameters, response parameters, error codes, authentication requirements, etc.) must be centralized in a dedicated "API Change List" block in 02-design.md.
• The API list format must allow frontend developers to directly use it for integration. Recommended fields: API path, request method, request body example, success response example, error code table, authentication requirements, notes.
• This API list is a deliverable to the frontend team and must be self-consistent and independently readable.
• The API list must provide definite conclusions during the design phase; it is forbidden to defer decisions to the implementation phase. Any fact that depends on existing code to be determined (e.g., "Is this API new or a change?", "Should the path be reused or modified?", "Which existing structure should the request parameters align with?") must be confirmed by reading existing code during the design phase, and the conclusion written into the API list. The constraint "only discuss, no code during design" applies to business code — reading existing code to confirm API shapes is design research, not implementation, and does not violate the constraint. The design document must not contain vague phrasing like "depends on existing code" or "to be confirmed during implementation," nor use tags like [Confirm during implementation] to legitimize uncertainty. When the API list is delivered to the frontend, it must be completely definite; otherwise the frontend cannot integrate.

Acceptance Criteria and Testing (Three-Layer Responsibility)

Testing is not an afterthought during implementation; it is a system that runs from design through implementation. Three layers with strictly separated responsibilities:

Layer	Carrier	Content	Nature	Produced In
Rules	02-design.md	Abstract acceptance criteria	"What level of satisfaction meets the requirement"	Design
Instances	04-test.md	Specific test cases	"What input, what expected output"	Implementation Planning
Actions	03-implementation.md	Steps + case references	"What action to take, against which case to verify"	Implementation Planning

Why this separation: Acceptance criteria define the requirement boundary (belong to design), test cases are the instantiation of that boundary, and implementation is the execution action. With three separate layers, changing rules means modifying the design document, changing cases means modifying the test document, and changing actions means modifying the implementation document — each has its own source of truth, without cross-contamination.

Test case layers and numbering:

Prefix	Type	Purpose
T-F-	Functional case	Positive flow
T-EX-	Exception case	Negative, boundary, error branches
T-R-	Regression case	Key paths mandatory after modification/rollback (selected from F/EX to prevent fixing A from breaking B)
T-API-	API case	Corresponds to each API in the design document's "API Change List"

All tasks must generate 04-test.md: This skill is designed for medium- to large-scale tasks; small requirements won't trigger the skill, so no complexity judgment is needed — once a task enters implementation planning, the test document is mandatory.

Relationship between modification/rollback and testing: After the modification or rollback mechanism is triggered, the plan changes → cases are updated (first modify the design acceptance criteria, then modify test cases), and the regression case set (T-R) must be run at least once to ensure local changes don't cause global regressions.

Extension Mode A: Task Decomposition (Large Multi-Module Tasks)

When to enable: Large tasks inherently contain multiple semi-independent modules (e.g., "Review System = Sensitive Word Filtering + Image Review + Manual Review Dashboard") that cannot fit in a single context. Enable when the user explicitly says "this is a large task, decompose it into multiple modules" during the discussion phase. Do not automatically judge task size; the user must explicitly trigger.

Core mechanism: The parent task is responsible for overall design + module decomposition + inter-module interface contracts + orchestration. Child tasks follow the complete 4-phase workflow within the boundaries defined by the parent task.

A.1 Parent and Child Task Document Structure (Nested)

project_root/docs/design/
├── README.md                          ← Global task overview
├── 01-review-system/                  ← Parent task
│   ├── 00-task-status.md              ← Uses parent-task-status.md template, includes child task list
│   ├── 01-communication.md            ← Parent-level overall discussion
│   ├── 02-design.md                   ← Overall architecture + module decomposition + inter-module interface contracts
│   ├── 03-implementation.md           ← Parent-level orchestration only (integration tests, coordination), not module internals
│   ├── 04-test.md                     ← Cross-module integration tests only
│   └── child-tasks/
│       ├── 01-1-sensitive-word-filter/ ← Child task (complete 4-phase docs, uses normal templates)
│       ├── 01-2-image-review/
│       └── 01-3-manual-review-dashboard/
└── 02-other-tasks/

Child tasks use normal templates (task-status / communication / design / implementation / test), identical to regular tasks. Parent tasks use the assets/parent-task-status.md template, which adds a "Child Task List" block. The parent task's design document, in addition to the normal design template, must include two extra blocks:

• Module Decomposition: List which child tasks are created, each with their scope and responsibilities
• Inter-Module Interface Contracts: Interface agreements between child tasks (interface signatures, data formats, invocation patterns, etc.). This is the key to enabling independent parallel execution of child tasks and must be finalized during the design phase.

A.2 Parent Task Phase Progression (Strictly Serial)

1. The parent task first goes through "Discussion + Design," must produce module decomposition + inter-module interface contracts
2. After the parent task's design is confirmed by the user, child tasks can be started
3. When starting child tasks, determine the start order based on dependency relationships: The parent task must identify inter-child dependencies during the design phase (e.g., "Manual Review Dashboard depends on the interface from Sensitive Word Filtering"). Dependencies must be completed before dependent tasks can start
4. Each child task goes through its own complete 4-phase workflow (can be parallel if dependencies are satisfied). How multiple child tasks are started in parallel depends on the agent framework (typically via background/asynchronous sub-task capabilities); for concrete implementation, see B.5
5. After all child tasks are complete, the parent task performs "cross-module integration tests" to wrap up

Why parent and child tasks cannot be parallel: The parent task's core output is the inter-module interface contracts — the prerequisite for child tasks to work independently. Starting child tasks before the parent task's design is finalized will inevitably cause conflicts between child tasks.

A.3 Child Tasks Cannot Unilaterally Modify the Interface Contracts Defined by the Parent Task

Interface contracts are the consensus across multiple modules. If any child task unilaterally changes them, other child tasks become unmanageable. If a child task finds an issue with the parent task's interface contracts:

• Cannot modify the interface contract on its own
• Must go back to the parent task and follow the modification mechanism: update the parent task's 02-design.md (including change log) → wait for user confirmation → notify all child tasks that depend on that interface → affected child tasks synchronously revise their own design/implementation/test documents

A.4 Nesting Depth Limit: Only One Level

Parent → Child, no further nesting allowed (child tasks cannot have their own child tasks). Reason: Excessive nesting makes task relationships extremely complex; if a child task still needs to be decomposed, it usually means the decomposition granularity is wrong — it should be re-planned as an independent parent task, not squeezed into an existing multi-layer structure.

A.5 Parent Task Template Usage

• Parent task status document: Use assets/parent-task-status.md (not the normal task-status template)
• Other parent task documents (communication/design/implementation/test): Use normal templates, but the design document must additionally include the two blocks described in A.1
• All child task documents: Use normal templates, completely unchanged

Extension Mode B: Dual Agent Implementation (Implementation Segmentation)

When to enable: Within a single task, the implementation + testing phases combined cause the context to become too long. Enable when the user explicitly says "use dual-agent mode for implementation" at the start of the implementation phase. Do not automatically judge; the user must explicitly trigger.

Core mechanism: The implementation phase itself is split into two serial stages — Implementer Agent (writes code per 03-implementation.md) + Tester Agent (verifies per 04-test.md). These are physically separate agents (two independent contexts), handing off via the task status document. The key value of B is context isolation: the implementer agent doesn't carry test context, and the tester agent doesn't carry implementation details.

B.1 Responsibility Boundary of Implementer and Tester

• Implementer agent: Only executes the steps in 03-implementation.md (writes code). After completion, does not run tests itself, but declares "Implementation complete, version X, ready for testing" in the "Implementation Segmentation Status" block of 00-task-status.md.
• Tester agent: Performs verification based on the latest 03-implementation.md and 04-test.md. Responsibility is strictly limited to "run cases, judge failures, report results." Not responsible for fixing code (even if it finds implementation bugs, it does not fix them).

B.2 Handling When the Tester Agent Finds Failures

When the tester agent runs test cases and finds failures, it initially judges the root cause (the tester agent sees the actual behavior and has the best information advantage for initial judgment):

• Judged as an implementation bug (code is wrong, design is correct) → Report to the implementer agent for fixing. After fixing, the tester agent must re-test that case; the case must pass before proceeding (the implementer agent's one-sided declaration of "fixed" is insufficient for closure).
• Judged as a design bug (code was written as designed, but the design itself is flawed) → Cannot modify the design without authorization — trigger the modification mechanism: Stop → Update design → Wait for user confirmation → Modify implementation → Modify tests → Return to tester agent for re-test

If the judgment is wrong, the user will correct it; but "changing the design" has a wide impact and requires user approval.

B.3 Implementation Segmentation Status Block

Add an optional block to 00-task-status.md (only filled when B mode is active; left empty in normal mode):

## Implementation Segmentation Status (B-mode only, leave empty for normal mode)

- Current stage: Implementation / Testing
- Implementation version: (incremented by the implementer agent after each completion or fix)
- Implementation completion declaration: YYYY-MM-DD, implementer agent has declared ready for testing
- Test progress:
  - Passed: T-F-01, T-F-02, ...
  - Failed, pending fix: T-EX-03 (implementation bug, reported to implementer agent), ...
  - Awaiting retest: T-EX-03 (implementer agent has fixed, waiting for tester agent to retest)

Both the implementer agent and tester agent read and write this block; it is their sole handoff point.

B.4 Combining with A (A+B)

A and B are orthogonal and can be combined: Large tasks are decomposed into child tasks via A; each child task internally uses B to split into implementation and testing. No additional mechanisms are needed for the combination — because child tasks are normal tasks (A.1 states child tasks use normal templates), so child tasks naturally support B. Activation method: After the parent task is designed and child tasks are started, each child task decides whether to enable B at the beginning of its implementation phase.

B.5 Agent Orchestration Guidelines

B mode requires two physically separate agents (implementer and tester), which hand off indirectly via the "Implementation Segmentation Status" block — they do not communicate directly. How exactly they take turns depends on the agent framework being used.

Regardless of the framework, follow the same general orchestration pattern:

1. An orchestrator (could be the main agent, an external script, or the user themselves) reads the "Implementation Segmentation Status" block to determine the current stage
2. The orchestrator starts the implementer agent, passing the paths to the design and implementation documents, instructing it to advance through 03-implementation.md and update the status block upon completion
3. After the implementation stage is done, the orchestrator starts the tester agent, passing the path to the test document, instructing it to run cases per 04-test.md and write results (including failure judgments) into the status block
4. The orchestrator determines the next step based on the test results in the status block: if an implementation bug, return to the implementer agent to fix and retest; if a design bug, stop and report to the user to follow the modification mechanism; if all pass, conclude.

General key points:

• The implementer agent and tester agent each establish their own independent context without cross-contamination — this is the core of B mode's "context isolation."
• The two agents do not directly perceive each other; they only hand off indirectly via the shared "Implementation Segmentation Status" block document.
• The orchestrator only does "read status → judge → dispatch" and does not participate in implementation or testing itself.

Concrete client-specific reference: Different agent frameworks have varying capabilities for sub-agents, background tasks, and multi-window support. This document does not lock into a specific implementation. When using ZCode, see assets/references/zcode-scheduling.md (loaded on demand: only read when B mode is enabled and concrete operational guidance is needed). Other clients can adapt to their own capabilities by referencing that file's approach.

Important boundary: The skill does not lock into a specific orchestration implementation

The skill defines the handoff protocol (format and semantics of the implementation segmentation status block) and the role responsibilities (what the implementer and tester each do), but does not lock into a specific orchestration method. Any framework that can "read files, start sub-tasks, and write files" can implement B mode.

Phase Transition Confirmation Principles

Phases do not automatically transition; they require explicit signals:

Entry Condition	Satisfaction Criteria
Enter Discussion	(Skill is manually activated to start)
Discussion → Design	User explicitly agrees to finalize the plan, and the unresolved questions list is empty
Design → Implementation Planning	Design document is complete and approved by the user
Implementation Planning → Implementation	User explicitly requests to start execution
Implementation → Design (Modification)	During implementation, a plan gap is found; follow the "modification mechanism" to stop and modify the design, wait for user confirmation
Implementation → Discussion/Design (Rollback)	During implementation, a fundamental error is found; AI suggests a rollback, user makes the final judgment, then roll back

If unsure whether to transition, default to staying in the current phase and continuing discussion; proactively ask the user. Do not make judgments like "the plan is good enough, we can start writing" on behalf of the user.

Template Usage

When creating new documents, read the corresponding template from the assets/ directory:

• assets/readme.md → docs/design/README.md (global task overview)
• assets/task-status.md → 00-task-status.md (normal task / child task)
• assets/parent-task-status.md → 00-task-status.md (parent task only, when A mode is enabled)
• assets/communication.md → 01-communication.md
• assets/design.md → 02-design.md (includes acceptance criteria block; parent tasks must additionally include module decomposition + interface contract blocks)
• assets/implementation.md → 03-implementation.md
• assets/test.md → 04-test.md (generated during implementation planning)

Read the template, fill in the actual content, and write it into the task folder. Do not fabricate document structures.

Skill Iteration and Legacy Task Documents

The skill will continue to evolve, and templates/specifications may be updated. However, existing task documents that are already in use will not be automatically migrated to new specifications. This is intentional — to protect the user's existing memory of the document structure and maintain the stability of the multi-context memory mechanism. The document structure is the memory anchor for users to quickly locate after switching contexts; anchors should not be frequently deformed due to skill upgrades.

Handling principles:

• No proactive migration: AI does not scan old tasks or proactively align them with new specifications, even if it finds discrepancies between old document formats and new specifications (e.g., an old document has a "Rollback Record" block while the new specification requires a "Change Log"). At most, mention the discrepancy in an "implementation memo" or dialogue, but do not act on it.
• Migrate only under explicit user instruction: Only act when the user explicitly requests, e.g., "align task X's documents with the current skill spec" or "migrate task X to the new format." AI does not decide for the user whether an old task should be migrated.
• Incremental supplementation preferred: Migration by default should only supplement/modify parts that do not conform to the new specification, preserving the overall structure and content of the original document. Do not rewrite everything. This way, when the user switches back to the context, they do not need to re-understand the entire document — the structure is unchanged, and the memory anchor remains.
• When the user explicitly requests a rewrite, support it, but back up the original file first before generating the new file:
  • Do not overwrite the original file directly
  • Add a date or version suffix to the backup file, e.g., 00-task-status.md.bak.20260617
  • The new file uses the original filename to carry the rewritten content
  • The original file is the user's historical memory anchor; even if rewritten, the original version must be preserved for comparison or rollback
• Explain the scope before migration/rewriting: Before starting, tell the user which parts will be changed (incremental) or which files will be rewritten (full), and briefly describe what was changed after completion to maintain predictability.

Anti-Patterns (To Avoid)

• ❌ Starting to write business code during the Discussion phase — putting the cart before the horse.
• ❌ Writing plan changes directly into the implementation document without updating the design document — breaking the single source of truth.
• ❌ Starting a new conversation without reading the status document and README, leaving the user to repeat progress — wasting context.
• ❌ Silently adjusting the implementation when encountering deviations without backfilling the design document — the design document gradually drifts from reality.
• ❌ Including frontend implementation details in a backend project, or not documenting API changes in the API change list — the frontend has no basis for integration.
• ❌ Automatically advancing phases without an explicit signal — depriving the user of decision-making power.
• ❌ When finding plan gaps (missing fields/branches/dictionary values, etc.) during implementation, directly modifying the implementation document without updating the design document and without waiting for user confirmation — should follow the "modification mechanism": stop → modify design first → wait for confirmation → modify implementation → continue.
• ❌ During implementation, finding a fundamental error but stubbornly continuing to modify the implementation document, or the AI unilaterally deciding to roll back — should follow the "rollback mechanism": AI can only suggest, user makes the final judgment, record the rollback, then return to Discussion/Design.
• ❌ Major step marked complete but minor steps still incomplete — both levels need independent marking.
• ❌ Discussion diverges without convergence, and unresolved questions are drowned by new topics — use the unresolved questions list to force convergence.
• ❌ Vague phrasing like "depends on existing code" or "to be confirmed during implementation" in the API list, or using tags like [Confirm during implementation] to legitimize uncertainty — facts depending on existing code must be confirmed during the design phase by reading the code; the API list must be completely definite when delivered; otherwise the frontend cannot integrate.
• ❌ After a skill iteration, proactively migrating or aligning old task documents to new specifications without the user's explicit instruction — destroys the user's memory anchor. Migrate only under explicit instruction; by default, make incremental supplements, not a full rewrite; when the user requests a rewrite, back up the original file first before generating the new one.
• ❌ The design document only describes the plan but lacks acceptance criteria — acceptance criteria define the requirement boundary; without them, there is no objective definition of "done," and implementation acceptance relies on gut feeling.
• ❌ The implementation document includes vague actions like "unit test coverage for XXX" without referencing specific case IDs — testing actions must point to concrete cases in 04-test.md (e.g., "verify against T-EX-03"); otherwise what to test and what to expect are unclear.
• ❌ Not running regression cases (T-R) after completing the modification/rollback mechanism — local changes may cause global regressions; key paths must be retested.
• ❌ In A mode, starting child tasks before the parent task's design is finalized (module decomposition or interface contracts not yet produced) — child tasks will inevitably conflict. The parent task's design must first be confirmed by the user.
• ❌ In A mode, a child task unilaterally modifies the interface contract defined by the parent task — interface contracts are multi-module consensus; must go back to the parent task and follow the modification mechanism, with notification to all child tasks depending on that interface.
• ❌ In A mode, a child task nests further child tasks (exceeding one layer) — usually indicates incorrect decomposition granularity; the child task should be re-planned as an independent parent task.
• ❌ In A mode, the parent task runs all child tasks in parallel without establishing dependency order — dependent tasks will be blocked waiting for uncompleted dependencies; dependency relationships must be clarified during the parent task's design phase.
• ❌ In B mode, the tester agent fixes implementation bugs itself — responsibilities must be separated: the tester only identifies issues, fixes go back to the implementer agent; and after fixing, the tester agent must re-test; the implementer agent cannot unilaterally declare closure.
• ❌ In B mode, using the same agent to sequentially act as both "implementer" and "tester" — the core value of B is context isolation; there must be physically two separate agents, otherwise the context is not isolated at all, and B mode is effectively not enabled.
• ❌ In B mode, the tester agent discovers a design bug and modifies the design itself — design changes have a wide impact and must trigger the modification mechanism and receive user confirmation; the tester agent can only make an initial judgment and report.