# 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.