Update Project Docs

Keeps every project doc in sync — both the core docs (README, GDD, whole-game plan, PROGRESS, CLAUDE) and any feature artifacts (surveys, specs, feature plans) that exist. Only touches the ones that are present; does not force a project to adopt every doc type.

Doc set (core + feature artifacts)

PROGRESS.md and CLAUDE.md are optional but recommended on any project larger than ~10 scenes. The docs/features/* trio only exists on projects that adopt feature-mode (trail B).

Decision flow

digraph update_flow {
    rankdir=TB;
    node [shape=diamond];
    start [label="What changed?" shape=doublecircle];
    impl [label="Code\nimplemented?"];
    design [label="Design\nchanged?"];
    arch [label="Architecture\nchanged?"];
    setup [label="Setup/install\nchanged?"];
    check [label="Cross-check"];
    node [shape=box];
    progress [label="Update PROGRESS.md\n(checkbox feature)"];
    gdd [label="Update GDD\n(docs/design/...-gdd.md)"];
    claudemd [label="Update CLAUDE.md\n(arch / convention)"];
    readme [label="Update README.md\n(install / overview)"];
    cross [label="Verify docs agree"];

    start -> impl;
    impl -> progress [label="yes"];
    impl -> design [label="no"];
    design -> gdd [label="yes"];
    progress -> design;
    gdd -> arch;
    design -> arch [label="no"];
    arch -> claudemd [label="yes"];
    arch -> setup [label="no"];
    claudemd -> setup;
    setup -> readme [label="yes"];
    setup -> check [label="no"];
    readme -> check;
    check -> cross;
}

Modes

Step 1 — Read current state

Always read all docs that exist before modifying any of them:

1. Read README.md                                                  -> overview baseline
2. Read docs/design/*-gdd.md (latest)                              -> design baseline (if exists)
3. Read docs/plans/*-plan.md  (latest, EXCLUDING *-feature-plan.md) -> whole-game plan baseline (if exists)
4. Read docs/features/*-survey.md  (each)                          -> feature surveys (if any)
5. Read docs/features/*-feature.md (each)                          -> feature specs (if any)
6. Read docs/plans/*-feature-plan.md (each)                        -> feature plans (if any)
7. Read PROGRESS.md                                                -> implementation status (if exists)
8. Read CLAUDE.md                                                  -> architecture baseline (if exists)

Glob discipline: the *-plan.md glob in step 3 also matches *-feature-plan.md files because the latter ends in -plan.md. Step 6 owns feature plans; step 3 must filter them out to avoid reading the same file twice. Use a globber that supports negation (docs/plans/*-plan.md minus docs/plans/*-feature-plan.md) or, in shell, ls docs/plans/*-plan.md | grep -v -- '-feature-plan\.md$'. In tooling-free contexts, list whole-game plans manually after enumerating with ls docs/plans/.

Then read code in scripts/, autoload/, scenes/ to verify what's actually implemented.

Step 2 — Update PROGRESS.md

For each feature touched, update its status:

- [ ]  -> not implemented (no code)
- [~]  -> partial (code exists but incomplete vs GDD)
- [x]  -> complete and matches GDD
- [?]  -> intentional divergence from GDD (document below)

Rules:

• Don't mark [x] if the feature works but diverges from GDD — use [?] and document.
• If a GDD feature has no entry in PROGRESS.md, add it.
• Update "Last updated: YYYY-MM-DD" at top of file.

Step 3 — Update GDD (only when design changed)

Modify only if:

• A mechanic was redefined
• A balance value was intentionally changed
• A new feature was designed (not just implemented)
• A [HYPOTHESIS] section was confirmed or discarded

Rules:

• Never edit the GDD to "match the code" — code follows GDD, not vice versa.
• If code intentionally diverges, document in PROGRESS.md "Divergences" section.
• Use gdd-writer skill for substantial design additions.

Step 4 — Update CLAUDE.md (only when architecture changed)

Modify only if:

• New autoload added
• New component / system module added
• New convention introduced (naming, file structure, signal pattern)
• New directory in project structure
• Tooling changed (new lint rule, new test framework)

Step 5 — Update README.md (only when overview changed)

Modify only if:

• Tech stack changed (Godot version bump, new addons required)
• Install / build / run command changed
• Project name, description, license, badges
• Quickstart broken

Step 6 — Cross-check

Verify pairwise consistency:

Common divergences to flag:

1. Feature [x] in PROGRESS but no code reference
2. Class described in CLAUDE.md but renamed/deleted in code
3. GDD value (e.g., "10 levels") differs from code constant (MAX_LEVELS = 12)
4. README mentions addon not in addons/

If divergence found, report to user before fixing — they decide whether to align doc to code or code to doc.

Divergences section in PROGRESS.md

Template:

## Divergences (GDD ↔ code)

1. **{Name}** — GDD says {X}. Code does {Y}.
   - Reason: {why we diverged}
   - Decision: {keep / align to GDD / update GDD}
   - Date: {YYYY-MM-DD}

Common mistakes