SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsrecipe-update-doc

recipe-update-doc

Design & creation

View repository

Updated 10-16 09:28

About this skill

Required Skills [LOAD BEFORE EXECUTION]

  1. [LOAD IF NOT ACTIVE] documentation-criteria — document creation rules and templates
  2. [LOAD IF NOT ACTIVE] subagents-orchestration-guide — agent coordination and workflow flows
  3. [LOAD IF NOT ACTIVE] llm-friendly-context — clear prompts, handoffs, and generated artifacts

Spawn rule: every spawn_agent call uses fork_turns="none" so the subagent receives only the task message and explicitly provided context.

Context: Dedicated to updating existing design documents.

Orchestrator Definition

Core Identity: "I am not a worker. I am an orchestrator." (see subagents-orchestration-guide skill)

First Action: Register Steps 1-6 before any execution.

Execution Protocol:

  1. Spawn agents for all work -- your role is to invoke sub-agents, pass data between them, and report results
  2. Execute update flow:
    • Identify target -> Clarify changes -> Update document -> Review -> Consistency check
    • [STOP — BLOCKING] At every [Stop: ...] marker -> Present status to user for confirmation. CANNOT proceed until user explicitly confirms.
  3. Scope: Complete when updated document receives approval

CRITICAL: MUST execute document-reviewer and all stopping points -- each serves as a quality gate for document accuracy. ENFORCEMENT: Skipping document-reviewer risks propagating inconsistencies to downstream workflows.

Workflow Overview

Target document -> [Stop: Confirm changes]
                        |
              technical-designer / technical-designer-frontend / prd-creator (update mode)
                        | (Design Doc only)
              code-verifier -> document-reviewer -> [Stop: Review approval]
                        | (Design Doc only)
              design-sync -> [Stop: Final approval]

Scope Boundaries

Included in this skill:

  • Existing document identification and selection
  • Change content clarification with user
  • Document update with appropriate agent (update mode)
  • Document review with document-reviewer
  • Consistency verification with design-sync (Design Doc only)

Out of scope (redirect to appropriate skills):

  • New requirement analysis -> $recipe-design
  • Work planning or implementation -> $recipe-plan or $recipe-task

Responsibility Boundary: This skill completes with updated document approval.

Target document: $ARGUMENTS

Execution Flow

Step 1: Target Document Identification

Check for existing documents in docs/design/, docs/prd/, docs/adr/.

Decision flow:

Situation Action
$ARGUMENTS specifies a path Use specified document
$ARGUMENTS describes a topic Search documents matching the topic
Multiple candidates found Present options to user
No documents found Report and end (suggest $recipe-design instead)

Step 2: Document Type and Layer Determination

Determine type from document path, then determine the layer to select the correct update agent:

Path Pattern Type Update Agent Notes
docs/design/*.md Design Doc technical-designer or technical-designer-frontend See layer detection below
docs/prd/*.md PRD prd-creator -
docs/adr/*.md ADR technical-designer or technical-designer-frontend See layer detection below

Layer detection (for Design Doc and ADR): Read the document and determine its layer from content signals:

  • Frontend (-> technical-designer-frontend): Document title/scope mentions React, components, UI, frontend; or file contains component hierarchy, state management, UI interactions
  • Backend (-> technical-designer): All other cases (API, data layer, business logic, infrastructure)

ADR Update Guidance:

  • Minor changes (clarification, typo fix, small scope adjustment): Update the existing ADR file
  • Major changes (decision reversal, significant scope change): Create a new ADR that supersedes the original

Step 3: Change Content Clarification [Stop]

[STOP — BLOCKING] Present change summary to user for confirmation. CANNOT proceed until user explicitly confirms.

Ask the user to clarify what changes are needed:

  • What sections need updating
  • Reason for the change (bug fix findings, spec change, review feedback, etc.)
  • Expected outcome after the update

Confirm understanding of changes with user before proceeding.

Step 4: Document Update

Spawn [Update Agent from Step 2] agent: "Operation Mode: update. Existing Document: [path from Step 1]. Changes Required: [Changes clarified in Step 3]. Update the document to reflect the specified changes. Add change history entry."

Step 5: Document Review [Stop]

For Design Doc updates, first verify the updated document against code:

Spawn code-verifier agent: "Verify the updated Design Doc against current code. doc_type: design-doc. document_path: [path from Step 1]. verbose: false. Focus especially on literal identifier referential integrity for concrete paths, endpoints, type names, config keys, and other exact identifiers changed in this update."

Store output as: $CODE_VERIFICATION_OUTPUT

For Design Doc updates: Spawn document-reviewer agent: "Review the following updated document. doc_type: DesignDoc. target: [path from Step 1]. mode: composite. code_verification: $CODE_VERIFICATION_OUTPUT. Focus on: Consistency of updated sections with rest of document, no contradictions introduced by changes, completeness of change history."

For PRD or ADR updates: Spawn document-reviewer agent: "Review the following updated document. doc_type: [PRD or ADR]. target: [path from Step 1]. mode: composite. Focus on: Consistency of updated sections with rest of document, no contradictions introduced by changes, completeness of change history."

Store output as: $STEP_5_OUTPUT

[STOP — BLOCKING] Present review results to user for approval. CANNOT proceed until user explicitly confirms.

On review result:

  • Approved -> Proceed to Step 6
  • Needs revision -> Return to Step 4 with review feedback (max 2 iterations): Spawn [Update Agent from Step 2] agent: "Operation Mode: update. Existing Document: [path from Step 1]. Review Feedback to Address: $STEP_5_OUTPUT. Address each issue raised in the review feedback."
  • After 2 rejections -> Flag for human review, present accumulated feedback to user and end

Present review result to user for approval.

Step 6: Consistency Verification (Design Doc only) [Stop]

[STOP — BLOCKING] Present consistency verification results to user for final approval. CANNOT proceed until user explicitly confirms.

Skip condition: Document type is PRD or ADR -> Proceed to completion.

For Design Doc, spawn design-sync agent: "Verify consistency of the updated Design Doc with other design documents. Updated document: [path from Step 1]"

On consistency result:

  • No conflicts -> Present result to user for final approval
  • Conflicts detected -> Present conflicts to user:
    • A: Return to Step 4 to resolve conflicts in this document
    • B: End and address conflicts separately

Error Handling

Error Action
Target document not found Report and end (suggest $recipe-design instead)
Sub-agent update fails Log failure, present error to user, retry once
Review rejects after 2 revisions Stop loop, flag for human intervention
design-sync detects conflicts Present to user for resolution decision

Completion Criteria

  • Identified target document
  • Clarified change content with user
  • Updated document via appropriate agent (update mode)
  • Ran code-verifier before document-reviewer for Design Doc updates
  • Spawned document-reviewer and addressed feedback
  • Spawned design-sync for consistency verification (Design Doc only)
  • Obtained user approval for updated document

Output Example

Document update completed.

  • Updated document: docs/design/[document-name].md
  • Approval status: User approved