Initial commit: Hermes skill spec-driven-infra

references/openspec-posthoc-wip-2026-09.md

@@ -0,0 +1,52 @@
+# 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.