# Docs Update > [Documentation] Holistic documentation orchestrator — detects impacted docs from git changes and updates project docs + business feature docs - Skill: `majiayu000/docs-update-2` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds add majiayu000/docs-update-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/docs-update-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: majiayu000 (https://skillmd.com/u/majiayu000) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/majiayu000/docs-update-2 --- > **[IMPORTANT]** Use `TaskCreate` to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ask user whether to skip. > **Critical Purpose:** Ensure ALL documentation stays in sync with code changes — project docs, business feature docs, and AI companions. > **External Memory:** For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in `plans/reports/` — prevents context loss and serves as deliverable. > **Evidence Gate:** MANDATORY IMPORTANT MUST — every claim, finding, and recommendation requires `file:line` proof or traced evidence with confidence percentage (>80% to act, <80% must verify first). ## Quick Summary **Goal:** Detect which documentation categories are impacted by recent code changes and update them accordingly. **Workflow:** 1. **Phase 0: Triage** — `git diff` to categorize what changed and which doc types are impacted 2. **Phase 1: Project Docs** — Update project-level docs (README, project-structure-reference, etc.) if impacted 3. **Phase 2: Business Feature Docs** — Detect affected modules, update existing feature docs in `docs/business-features/` 4. **Phase 3: Summary Report** — What was checked, updated, and skipped **Key Rules:** - NEVER create new business feature docs from scratch — only update existing ones - Fast exit when no documentation is impacted (e.g., only `.claude/` config changes) - Always report what was checked, even if nothing needed updating --- **Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).** ## Phase 0: Triage — Detect Impacted Documentation ### Step 0.1: Collect Changed Files 1. Run `git diff --name-only HEAD` (captures both staged and unstaged changes) 2. If no uncommitted changes, run `git diff --name-only HEAD~1` (last commit) 3. If still empty, run `git diff --name-only origin/develop...HEAD` (branch changes) ### Step 0.2: Categorize Changes Classify each changed file into documentation impact categories: | Changed File Pattern | Impact Category | Action | | ----------------------------------------------------------------------------------- | ------------------------------- | ----------------- | | `src/Services/**` | **feature-docs** + project-docs | Phase 1 + Phase 2 | | `{frontend-apps-dir}/**`, `{frontend-libs-dir}/{domain-lib}/**` | **feature-docs** + project-docs | Phase 1 + Phase 2 | | `{legacy-frontend-dir}/**Client/**` | **feature-docs** + project-docs | Phase 1 + Phase 2 | | `src/{Framework}/**` | project-docs | Phase 1 only | | `docs/**` | project-docs | Phase 1 only | | `.claude/**`, config files only | **none** | Fast exit | | `{frontend-libs-dir}/{platform-core-lib}/**`, `{frontend-libs-dir}/{common-lib}/**` | project-docs | Phase 1 only | ### Step 0.3: Fast Exit Check If ALL changed files fall into the **none** category (e.g., only `.claude/`, `.github/`, root config files): - Report: `"No documentation impacted by current changes (config/tooling only)."` - **Exit early** — skip Phase 1 and Phase 2. --- ## Phase 1: Project Documentation Update **When to run:** Changed files include `src/{Framework}/**`, `docs/**`, or architectural changes. **When to skip:** Only service-layer or frontend feature files changed (no architectural impact). Skip and proceed to Phase 2. ### Step 1.1: Spawn Scouts (standalone invocation only) When invoked standalone (not as a workflow step), spawn scouts for broad codebase context: 1. Spawn 2-4 `scout-external` (preferred) or `scout` (fallback) via Task tool 2. Target directories that actually exist — adapt to project structure 3. Merge scout results into context summary **When invoked as a workflow step:** Skip scouting — use git diff context from Phase 0 directly. ### Step 1.2: Update Project Docs Pass context to `docs-manager` agent to update impacted project docs: - `docs/project-reference/project-structure-reference.md`: Update if service architecture or cross-service patterns changed - `README.md`: Update if project scope or setup changed (keep under 300 lines) Only update docs that are **directly impacted** by the changes. Do not regenerate all docs. --- ## Phase 2: Business Feature Documentation Update > **This phase replaces the need to invoke `/feature-docs` separately for update scenarios.** > docs-update handles the full update lifecycle: detection → analysis → update → verification. > Only invoke `/feature-docs` directly when **creating new feature docs from scratch**. **When to run:** Changed files match `src/Services/**`, `{frontend-apps-dir}/**`, `{frontend-libs-dir}/{domain-lib}/**`, or `{legacy-frontend-dir}/**Client/**`. **When to skip:** No service-layer or frontend feature files changed. Report: `"No business feature docs impacted."` ### Step 2.1: Auto-Detect Affected Modules Extract unique module names from changed file paths: | Changed File Path Pattern | Detected Module | | --------------------------------------------------- | -------------------------------- | | `src/Services/{Module}/**` | {Module} | | `{frontend-apps-dir}/{app-name}/**` | {Module} (map app to module) | | `{frontend-libs-dir}/{domain-lib}/src/{feature}/**` | {Module} (map feature to module) | | `{legacy-frontend-dir}/{Module}Client/**` | {Module} | Build project-specific mapping by examining: ```bash ls -d src/Services/*/ ls -d docs/business-features/*/ ``` ### Step 2.2: Check Existing Docs For each detected module: 1. Check if `docs/business-features/{Module}/` exists 2. Check if `docs/business-features/{Module}/detailed-features/` has feature docs 3. **If docs exist** → proceed to Step 2.3 (update mode) 4. **If no docs exist** → report: `"Module {Module} has no feature docs. Consider running /feature-docs to create them."` and skip ### Step 2.3: Diff Analysis 1. Categorize changes by type: backend entity, command, query, frontend component, i18n, etc. 2. Map each change to impacted documentation sections using the table below ### Step 2.4: Section Impact Mapping | Change Type | Impacted Doc Sections | | ---------------------- | ---------------------------------------------------------------------------------------- | | New entity property | 3 (Business Requirements), 9 (Domain Model), 10 (API Reference) | | New API endpoint | 10 (API Reference), 12 (Backend Controllers), 14 (Security) | | New frontend component | 11 (Frontend Components) | | New filter/query | 3 (Business Requirements), 10 (API Reference) | | New i18n keys | 11 (Frontend Components) | | Any new functionality | **17 (Test Specs), 18 (Test Data), 19 (Edge Cases), 20 (Regression Impact)** — MANDATORY | | Any change | 1 (Executive Summary), 26 (Version History) — ALWAYS UPDATE | ### Step 2.5: Update Impacted Sections For each module with existing docs: 1. Read the existing feature doc (`README.{FeatureName}.md`) 2. Update ONLY the sections identified in Step 2.4 3. **Mandatory test coverage** — when documenting new functionality, MUST update: - Section 17 (Test Specifications): Add TC-{MOD}-XXX test cases with GIVEN/WHEN/THEN - Section 18 (Test Data): Add seed data for new test cases - Section 19 (Edge Cases): Add boundary conditions and error states - Section 20 (Regression Impact): Add regression risk rows 4. Update Section 26 (Version History) with new version entry 5. Add CHANGELOG entry under `[Unreleased]` following Keep a Changelog format ### Step 2.6: AI Companion Sync If `README.{FeatureName}.ai.md` exists alongside the updated feature doc: - Update the AI companion to reflect changes (keep 300-500 lines) - Update `Last synced` timestamp ### Step 2.7: Verification (Mandatory) After updating feature docs, run a verification pass on all changed sections: 1. **Evidence audit** — Every test case (TC-{MOD}-XXX) MUST have `file:line` evidence. Read the claimed file at the claimed line and verify the code supports the assertion. Fix immediately if wrong. 2. **Domain model check** — Verify entity properties, types, and enum values against actual source code. Remove anything not found in source. 3. **Cross-reference audit** — Test Summary counts match actual TC count. No template placeholders remain (`{FilePath}`, `{LineRange}`). All internal links resolve. **If verification finds hallucinated or stale content → fix before completing Phase 2.** ### Step 2.8: TC Coverage Cross-Reference After updating feature docs, cross-reference integration test TC codes against doc TC codes: 1. Use the Grep tool to find all `[Trait("TestSpec", ...)]` in the affected service's integration test project: ``` Grep pattern="Trait\(\"TestSpec\"" path="src/Services/{ServiceDir}/{Service}.IntegrationTests" glob="*.cs" ``` 2. Use the Grep tool to find all `TC-{MOD}-XXX` in the affected feature doc Section 17 / test-specs doc: ``` Grep pattern="TC-[A-Z]{2,}-[0-9]+" path="docs/business-features/{Module}/detailed-features" glob="*.md" ``` 3. Compare the TC codes found: - TC in docs but no Trait in code → flag as `Status: Untested` in the doc - Trait in code but no TC in docs → add TC entry to the feature doc Section 17 4. Report discrepancies in the Phase 3 Summary Report ### Decision: When docs-update Handles It vs. When to Recommend /feature-docs | Scenario | Action | | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | Existing docs + code changes | **docs-update handles it** (Steps 2.1–2.7 above) | | No existing docs for module | Report: recommend `/feature-docs` for creation | | Major new feature (new entity, new service, >10 new endpoints) | **docs-update handles update**, but report: "Consider full `/feature-docs` review for completeness" | | User explicitly asks for full 26-section doc | Defer to `/feature-docs` | --- ## Phase 3: Summary Report Always output a summary of what happened: ``` ### Documentation Update Summary **Triage:** {N} files changed → {categories detected} **Project Docs:** - {Updated/Skipped}: {reason} **Business Feature Docs:** - Module {X}: {Updated sections A, B, C / No existing docs / Not impacted} - Module {Y}: {Updated sections D, E / Skipped: no feature docs} **Recommendations:** - {Any new docs that should be created} - {Any stale docs flagged but not auto-fixed} ``` --- ## Additional Requests $ARGUMENTS --- ## Next Steps **MANDATORY IMPORTANT MUST** after completing this skill, use `AskUserQuestion` to recommend: - **"/watzup (Recommended)"** — Wrap up session and check for remaining doc staleness - **"/review-changes"** — Review all changes before commit - **"Skip, continue manually"** — user decides ## Closing Reminders **MANDATORY IMPORTANT MUST** break work into small todo tasks using `TaskCreate` BEFORE starting. **MANDATORY IMPORTANT MUST** validate decisions with user via `AskUserQuestion` — never auto-decide. **MANDATORY IMPORTANT MUST** add a final review todo task to verify work quality.