GM UPDATE-DOCS — Documentation Refresh
You are in the UPDATE-DOCS phase. Feature work is verified and pushed. Refresh all documentation to match the actual codebase state right now.
GRAPH POSITION:
PLAN → EXECUTE → EMIT → VERIFY → [UPDATE-DOCS] → COMPLETE
- Entry: Feature work verified, committed, and pushed. Entered from .
TRANSITIONS
FORWARD: All docs updated, committed, and pushed → COMPLETE (session ends)
BACKWARD:
- Diff reveals unknown architecture change → invoke skill, restart chain
- Doc write fails post-emit verify → fix and re-verify before advancing
EXECUTION SEQUENCE
Step 1 — Understand what changed:
exec:bash
git log -5 --oneline
git diff HEAD~1 --stat
Witness which files changed. Identify doc-sensitive changes: new skills, new states in the state machine, new platforms, modified architecture, new constraints, renamed files.
Step 2 — Read current docs:
exec:nodejs
const fs = require('fs');
['README.md', 'CLAUDE.md', 'docs/index.html',
'plugforge-starter/agents/gm.md'].forEach(f => {
try { console.log(`=== ${f} ===\n` + fs.readFileSync(f, 'utf8')); }
catch(e) { console.log(`MISSING: ${f}`); }
});
Identify every section that no longer matches the actual codebase state.
Step 3 — Write updated docs:
Write only sections that changed. Do not rewrite unchanged content. Rules per file:
README.md: platform count matches adapters in
, skill tree diagram matches current state machine, quick start commands work.
CLAUDE.md: Only non-obvious technical caveats that required multiple runs to discover — things that could not be known without hitting the problem first. Remove anything that no longer applies. Never add anything obvious from reading the code or that any developer would already know. The test: "would a developer need to discover this the hard way, or is it self-evident?" If self-evident, exclude it.
docs/index.html:
array matches current skill state machine phases. Platform lists match
directory. State machine diagram updated if new phases added.
plugforge-starter/agents/gm.md: Skill chain on the
line updated if new skills were added.
exec:nodejs
const fs = require('fs');
fs.writeFileSync('/abs/path/file.md', updatedContent);
Step 4 — Verify from disk:
exec:nodejs
const fs = require('fs');
const content = fs.readFileSync('/abs/path/file.md', 'utf8');
console.log(content.includes('expectedString'), content.length);
Witness each written file from disk. Any variance from expected content → fix and re-verify.
Step 5 — Commit and push:
exec:bash
git add README.md CLAUDE.md docs/index.html plugforge-starter/agents/gm.md
git diff --cached --stat
Witness staged files. Then commit and push:
exec:bash
git commit -m "docs: update documentation to reflect session changes"
git push -u origin HEAD
Witness push confirmation. Zero variance = COMPLETE.
DOC FIDELITY RULES
Every claim in docs must be verifiable against disk right now:
- State machine phase names must match skill file frontmatter
- Platform names must match adapter class names in
- File paths must exist on disk
- Constraint counts must match actual constraints
If a doc section cannot be verified against disk: remove it, do not speculate.
CONSTRAINTS
Never: skip diff analysis | write docs from memory alone | push without verifying from disk | add comments to doc content | claim done without witnessed push output
Always: witness git diff first | read current file before overwriting | verify each file from disk after write | push doc changes | confirm with witnessed push output
→ COMPLETE: Docs committed and pushed → session ends.
↩ SNAKE to PLAN: New unknown about codebase state → invoke
skill.