recipe-update-doc

Required Skills [LOAD BEFORE EXECUTION]

Before loading required skills, use wc -c to size the files and set both exec_command.max_output_tokens and the outer // @exec: {"max_output_tokens": N} budget to accommodate their contents, including the combined output of batched reads. Split oversized reads upfront; recover any truncated content before proceeding.

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 — document update and review handoffs

Invocation rule: Start each named agent with spawn_agent and fork_turns="none". When invoking the same named agent again within this flow, use followup_task on its existing instance with the inputs specified for the current invocation.

Context: Dedicated to updating existing design documents.

Orchestrator Definition

Core Identity: Coordinate document updates, perform lightweight routing and status changes directly, and invoke document specialists for semantic authoring and review.

Execution Plan: Reuse the active execution plan. When the workflow has multiple dependent actions and no plan exists, create one that tracks them through final verification.

Execution Protocol:

1. Invoke the named author and reviewer for document judgment; perform artifact selection, routing, explicit-answer application, and status updates directly
2. Execute update flow:
   • Identify target -> Clarify changes -> Update document -> Review -> Consistency check
   • Ask for missing change intent only when it cannot be recovered from the request and target document
3. Scope: Return the reviewed update through Step 6

Execute document-reviewer before completion; Step 6 owns finalization.

Workflow Overview

Target document -> Clarify changes -> update agent
                                      |
                    [Design Doc: code-verifier -> Review Resolution]
                                      |
                              document-reviewer
                                      |
                         [Design Doc: design-sync]
                                      |
                        [Step 6: Finalize update]

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)

Responsibility Boundary: This skill completes with the reviewed update finalized under Step 6.

Target document: $ARGUMENTS

Execution Flow

Step 1: Target Document Identification

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

Decision flow:

Step 2: Document Type and Layer Determination

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

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

Derive the sections, reason, and expected outcome from the user request and target document. Ask only for a missing item whose plausible interpretations would materially change the updated document.

For PRD or Design Doc updates, apply the requested changes to the target document's current outcome, requirements, and exclusions to form requirement_context; preserve fields the request does not change. Incorporate later user corrections or additions into the same context before the next update or review action. For ADR updates, use requirement_context: N/A — ADR update and carry the accepted decision plus the requested changes as governing context.

Step 4: Document Update

For PRD or Design Doc, invoke [Update Agent from Step 2]: "Operation Mode: update. Existing Document: [path from Step 1]. Changes Required: [the change request and Step 3 answers, as given]. requirement_context: [Step 3 current context]. Update the document to reflect the specified changes. Add change history entry."

For a minor ADR change, invoke the update agent with Operation Mode: update, the existing path, the requested changes, and requirement_context: N/A — ADR update. For a major ADR change, apply documentation-criteria's choice and durability filters. Update or retire an unnecessary choice in the existing record; create a superseding ADR only for a qualifying new decision. Existing execution authority remains valid for outcome-preserving technical reductions.

Step 5: Document Review

Review reception: Unnecessary repairs create lasting work. Before assigning a fix, use Review Resolution to judge no change, removal or narrowing, and reuse first; record why any retained or added mechanism is necessary.

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

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

Apply Review Resolution to every discrepancy. Pass the apply discrepancies to the update agent, rerun code-verifier, and store the resolved summary, declines with reasons, and material limitations as $VERIFICATION_RESOLUTION after the apply set becomes empty.

For Design Doc updates: Invoke document-reviewer agent: "Review the following updated document. doc_type: DesignDoc. review_context: update. target: [path from Step 1]. requirement_context: [Step 3 current context]. verification_resolution: $VERIFICATION_RESOLUTION. Focus on consistency of the updated sections, governing requirements, and change history."

For PRD updates, invoke document-reviewer with the target and requirement_context from Step 3. For minor ADR updates, use doc_type: ADRBatch, targets: [updated ADR path], and review_context: update; review the requested changes and their dependent consistency while carrying the accepted, unchanged decision content as governing context.

Store output as: $STEP_5_OUTPUT

On review result:

• pass -> proceed to Step 6
• needs_revision -> Apply Review Resolution with the update agent, then review the updated document
• rejected -> Apply Orchestrator Escalation Resolution. Continue after self-resolution; ask the user only when that procedure reaches a user-decision condition

Step 6: Consistency Verification and Finalization

For PRD or ADR, proceed directly to finalization below.

For Design Doc, invoke 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 -> Finalize the update below
• Conflicts detected -> Apply Orchestrator Escalation Resolution using both governing documents. Return affected sources to their responsible authors, including previously passed technical decisions; ask the user only when required outcomes, explicit constraints, or execution authority must change

Finalize the update: Return an outcome-preserving technical correction to its calling workflow under existing authority. For a standalone update or a changed user-owned decision, present the reviewed result and obtain any confirmation still required by the shared Explicit Stop Points. Report whether the update returned to its caller or received that confirmation.

Error Handling

Completion Criteria

• Identified target document
• Resolved change content from the request and target document, asking only when material intent was missing
• Built the current requirement_context from the target document and the requested changes
• Updated document via appropriate agent (update mode)
• Applied Review Resolution to code-verifier discrepancies before document-reviewer for Design Doc updates
• Invoked document-reviewer and addressed feedback
• Invoked design-sync for consistency verification (Design Doc only)
• Finalized the update under Step 6

Output Example

Document update completed.

• Updated document: docs/design/[document-name].md
• Continuation: [returned to calling workflow / user confirmation received]