spec-driven-infra/references/openspec-posthoc-wip-2026-09.md

Post-hoc documentation & WIP with OpenSpec (2026-09-06 session)

Two real patterns proven on infra tasks: recording ALREADY-DONE work, and leaving a change honestly open when verification is blocked.

Pattern 1: Post-hoc documentation of completed work

OpenSpec normally drives work before implementation, but it also records work that is already done (hotfix, config tuned before spec). Flow:

1. openspec new change "<kebab-case-name>"
2. Write the 4 artifacts describing what was done:
   • proposal.md — why + what changed (past tense fine)
   • specs/<cap>/spec.md — delta requirements ADDED, with GIVEN/WHEN/THEN scenarios
   • design.md — approach, files touched, commands, rollback
   • tasks.md — every step ticked [x] only if genuinely done & verified
3. openspec validate <name> (must pass)
4. openspec archive <name> --yes → delta merges into openspec/specs/<cap>/spec.md, change moves to openspec/changes/archive/<date>-<name>/

Result: clean dated record; main specs gain the requirement. Proven with tavily-proxy-setup (Tavily web_extract via local HTTP→SOCKS5 forwarder — 3 requirements merged, archived cleanly).

Pattern 2: Keep WIP open when verification is blocked

openspec archive refuses incomplete tasks. When some tasks can't be verified (network tests needing user presence, flaky external API, blocked commands), do not force-archive with --yes — you'd be recording unverified work as done.

Instead leave the change in changes/<name>/. It is a valid WIP state:

openspec status --change <name>
  Progress: 4/4 artifacts complete
  [x] proposal   [x] specs   [x] design   [x] tasks
# but tasks.md still has un-checked boxes → resume point is obvious

Next session: openspec status --change <name> shows what's left; finish tasks, openspec validate, openspec archive. Proven with local-extractor (2 network tests blocked while user was away → change left open, honest).

Layout traps

• Archived changes live in openspec/changes/archive/<date>-<name>/ — nested under changes/, not a top-level openspec/archive/. find openspec -name design.md to locate them after archiving.
• Editing an archived change afterwards = editing openspec/changes/archive/<date>-<name>/design.md (documentation updates for accuracy), not the pre-archive path.