Sdd Update

SDD Update

Keeps the system design document in sync with the actual code. Works with any design doc (sdd.md, design.md, architecture.md, ARCHITECTURE.md, or equivalent).

Source: Adapted from the TrueRate project workflow. Level-check integration based on 5 Levels of Claude Code and DennisWei9898/claude-context-kit.

Pre-flight: Level check

echo "L2:$(wc -l < CLAUDE.md 2>/dev/null || echo 'MISSING')" && \
echo "L3-rules:$(ls .claude/rules/*.md 2>/dev/null | wc -l | tr -d ' ')" && \
echo "L3-skills:$(ls .claude/skills/*/SKILL.md 2>/dev/null | wc -l | tr -d ' ')" && \
ls sdd.md design.md architecture.md ARCHITECTURE.md 2>/dev/null | head -1

If no design doc is found, ask the user which file to treat as the SDD before proceeding.

If the project is below Level 3, note it but don't block — updating the design doc is itself a Level 2→3 improvement.

Locate what changed

Find the design doc and understand the scope of recent changes. Look at:

git diff --name-only HEAD~5 HEAD 2>/dev/null | head -30
git log --oneline -10 2>/dev/null

Or ask the user: which feature/module was just implemented?

What to update

Read the SDD and the code side-by-side. Only update sections where the code actually changed. Common update points:

Rule: If the code and SDD conflict, the code wins. Update the SDD to match code, not vice versa.

Version stamp

After updating, bump the version in the SDD header:

> Version: v{old + 0.1}
> Updated: {today's date}
> Changes: {one-line summary of what was updated}

Check .claude/rules/ for drift

If .claude/rules/product.md or .claude/rules/tech-stack.md reference the changed areas, check them for consistency too. Rules files and the SDD should not contradict each other.

Constraints

• Only update sections that actually changed — don't touch unrelated sections
• Remove deprecated endpoints/fields entirely — don't add "deprecated" comments
• Never run git commands after updating — the user decides when to commit
• Don't update settings.json or settings.local.json

Gotchas

• If the SDD has a table of contents with anchor links, check that headings still match after editing
• DB schema in SDD often drifts faster than API docs — check both when in doubt
• "Update the SDD" often means "and also check if the rules files are still accurate" — do both
• If the SDD is > 500 lines with no table of contents, suggest adding one (but don't do it without asking)
• After adding a new API endpoint to the SDD, also check if .claude/rules/tech-stack.md has a key-endpoints section that needs updating
• Phase markers (✅ / ⏸) in the SDD should reflect actual code state, not the plan — if something was planned but not implemented, it stays ⏸