mirror of
https://gitverse.ru/kpa39l/spec-driven-infra.git
synced 2026-09-29 21:25:05 +00:00
estorozhenko
52 lines
2.3 KiB
Markdown
52 lines
2.3 KiB
Markdown
# 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. |