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**: | 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 that the requested update target does not exist and end | ### 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 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 confirmed changes to the target document's current outcome, requirements, and exclusions to form `confirmed_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 `confirmed_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]. confirmed_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, confirmed changes, and `confirmed_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]. confirmed_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 `confirmed_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 | Error | Action | |-------|--------| | Target document not found | Report that the requested update target does not exist and end | | Sub-agent update fails or returns an unusable result | Apply Orchestrator Escalation Resolution | | Review Resolution requires a user-owned decision | Apply Orchestrator Escalation Resolution | | design-sync detects conflicts | Apply Orchestrator Escalation Resolution against the governing sources | ## Completion Criteria - [ ] Identified target document - [ ] Resolved change content from the request and target document, asking only when material intent was missing - [ ] Built the current `confirmed_requirement_context` from the target document and confirmed 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]