documentation-workflow

What It Does

Runs the two-stage post-onboarding documentation workflow.

Stage 1 — Foundation (create documentation) Generates docs/instructions/** (stack, architecture, design-system, registries, benchmarks, tech-debt) and writes docs/instructions/rules/module-map.yml. Module docs are explicitly deferred until the user reviews the map.

Stage 2 — Module documentation (create module documentation) Reads docs/instructions/rules/module-map.yml as the sole authority for module and feature names, then generates docs/modules/**. Refuses to run if the map is absent.

Use This When

• documentation-update workflow: Run Stage 1. Use for post-onboarding, stack-validation, or drift-refresh runs where instruction docs need to be created or regenerated.
• module-documentation workflow: Run Stage 2. Use only after the user has reviewed module-map.yml and confirmed business-language names.

Inputs

• Read .paqad/project-profile.yaml, .paqad/detection-report.json, and .paqad/doc-progress.json if they exist.
• For Stage 2: require docs/instructions/rules/module-map.yml. Refuse if absent.

Procedure — Stage 1 (foundation)

1. Validate the effective stack and capabilities against current manifests.
2. Recover any interrupted tracker entries still marked in-progress.
3. Generate or update docs/instructions/stack/**, docs/instructions/architecture/**, docs/instructions/design-system/**, docs/instructions/registries/**, docs/instructions/benchmarks/**, and docs/instructions/tech-debt/**.
4. Discover business modules from the codebase using the precedence order defined in the spec (user-provided → locked map entries → codebase-native containers → deterministic inference → LLM fallback).
5. Write or update docs/instructions/rules/module-map.yml.
6. Record .paqad/doc-progress.json with moduleDocStage: pending_map_review.
7. **Do not create or regenerate docs/modules/**.**
8. End with the required message:

Module map written to docs/instructions/rules/module-map.yml.
Review and verify the module and feature names first. After the map is correct, prompt me with: create module documentation.