[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:

• Phase 0: Triage — git diff to categorize what changed and which doc types are impacted

• Phase 1: Project Docs — Update project-level docs (README, project-structure-reference, etc.) if impacted

• Phase 2: Business Feature Docs — Detect affected modules, update existing feature docs in docs/business-features/

• 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

• Run git diff --name-only HEAD (captures both staged and unstaged changes)

• If no uncommitted changes, run git diff --name-only HEAD~1 (last commit)

• 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:

• Spawn 2-4 scout-external (preferred) or scout (fallback) via Task tool

• Target directories that actually exist — adapt to project structure

• 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:

ls -d src/Services// ls -d docs/business-features//

Step 2.2: Check Existing Docs

For each detected module:

• Check if docs/business-features/{Module}/ exists

• Check if docs/business-features/{Module}/detailed-features/ has feature docs

• If docs exist → proceed to Step 2.3 (update mode)

• 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

• Categorize changes by type: backend entity, command, query, frontend component, i18n, etc.

• 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:

• Read the existing feature doc (README.{FeatureName}.md )

• Update ONLY the sections identified in Step 2.4

• 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

• Update Section 26 (Version History) with new version entry

• 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:

• 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.

• Domain model check — Verify entity properties, types, and enum values against actual source code. Remove anything not found in source.

• 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:

• 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"

• 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"

• 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

• 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

<additional_requests> $ARGUMENTS </additional_requests>

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.