@inkeep/open-knowledge 0.46.0-beta.6 → 0.46.0-beta.8

package/dist/assets/skills/packs/software-lifecycle/write-a-postmortem/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: open-knowledge-pack-software-lifecycle-write-a-postmortem
+description: "Write a blameless incident postmortem under postmortems/ following the Google SRE shape — evidence-based timeline, trigger vs root cause vs symptom, contributing factors, what went well, and owned+dated+verifiable action items. Read when asked to write a postmortem, do an incident review, run a root cause analysis, write up the outage, retro on the outage, or when the user says we had an incident and wants it documented. Do NOT read to frame a proposal (use frame-a-proposal), write a spec (use write-a-spec), record a decision (use record-a-decision), or review a design (use review-a-design) — a postmortem documents an incident that already happened, it does not propose, specify, decide, or critique future work."
+compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack software-lifecycle`."
+metadata:
+  pack: "software-lifecycle"
+  author: "Inkeep"
+  repository: "https://github.com/inkeep/open-knowledge"
+---
+
+# Write a postmortem
+
+The platform `open-knowledge` skill still governs every markdown operation here — folder scope, the read/write tool surface, linking, and preview. This skill layers postmortem craft on top of it; it does not replace those rules.
+
+A postmortem is not a status update and not a blame ledger. It is a durable, blameless reconstruction of one incident, built from evidence, that makes the system's failure mode legible and produces action items someone will actually verify. The value compounds only when postmortems that share a subsystem link to each other — that is how a repeat class stops being invisible.
+
+This pack scaffolds `proposals/`, `decisions/`, `specs/`, `postmortems/`, and `guides/` at the project root. Postmortems live in `postmortems/`, one file per incident, filename `YYYY-MM-DD-name.md`, template id `postmortem`. Action items that are guide-shaped produce `runbook` stubs in `guides/`.
+
+The knowledge base is markdown owned by OpenKnowledge MCP. Read and list in-scope markdown with `exec` (`exec("ls -A postmortems/")`, `exec("cat postmortems/2024-03-02-auth-outage.md")`, `exec("grep -rln failover .")`) and `search({ query: "..." })`; create and edit with `write` and `edit`; inspect the link graph with `links`. Never use native Read/Edit/Grep/Glob/`cat` on in-scope markdown. Source code, logs, dashboards, deploy history, and chat transcripts are OUTSIDE the knowledge base — read those with the host's native tools. Links are plain markdown relative links `[db failover](./guides/db-failover.md)` — never backticked, never HTML anchors.
+
+---
+
+## Step 0 — Blamelessness gate (stated first because it constrains every later step)
+
+Blameless is a mechanical discipline, not a slogan you paste in the header. If you cannot follow these rules mechanically, the document is not blameless no matter what it says at the top.
+
+- **Name systems and roles, never individuals.** "the deploy pipeline," "the on-call engineer," "the release process" — not "Alice," not "the new hire." A named person turns readers defensive and the analysis stops.
+- **Write the system's affordance, not the person's action.** "The deploy pipeline allowed an unreviewed config to reach production" — not "Alice deployed an unreviewed config." The grammatical subject is the system that permitted the outcome. If your sentence's subject is a person, rewrite it until it is a system.
+- **Treat every human action as the reasonable action given the information available at that moment.** Nobody caused the incident by being careless. Someone did the sensible thing with the signals they had. The analytical question is never "why did they do that?" — it is "what made that look like the right move at the time?" A dashboard that read green, an alert that never fired, a runbook that said to do exactly that. Find the thing that made it reasonable; that thing is a contributing factor.
+
+**HARD GATE.** If the user's framing is blame-seeking — "write up how Alice broke prod," "document who screwed up the deploy" — do not comply as asked. Say so plainly, reframe to the system question, and only then write. Example reframe: "I'll write this blamelessly — the useful question isn't who pushed the config but what let an unreviewed config reach production. That's the finding that prevents a recurrence." Producing a named-culprit document because the user asked for one is the single worst failure this skill can commit; it poisons the postmortem culture the document is supposed to build.
+
+---
+
+## Step 1 — Gather evidence before you narrate
+
+You cannot write a timeline from memory and call it a postmortem. Gather first, narrate second.
+
+Pull, using the host's native tools (these live outside the knowledge base):
+
+- **Alerts and monitoring** — what fired, when, and what did not fire that should have.
+- **Deploy and release history** — what shipped in the hours before, and the exact commit/config.
+- **Dashboards and metrics** — error rate, latency, saturation, the graphs that show onset and recovery.
+- **Chat transcripts and the incident channel** — timestamps of human decisions and the reasoning in the moment.
+- **The code and config as it stood at incident time** — not as it stands now; check out or read the state at the incident SHA.
+
+**HARD GATE — no timeline entry without a source you can point at.** Every timeline line cites its evidence: an alert ID, a deploy timestamp, a graph, a chat message time. If you are reconstructing a moment from someone's recollection and have no artifact, you may still include it — but label it inline: `(reconstructed from recollection, no artifact)`. A postmortem whose timeline silently blends logged fact with memory is worse than one that admits the gap, because the reader cannot tell which numbers to trust.
+
+---
+
+## Step 2 — Scan prior postmortems for the same subsystem
+
+Before writing, find out whether this already happened.
+
+1. `exec("ls -A postmortems/")` — see every prior incident at a glance.
+2. `search({ query: "<subsystem> <failure mode>" })` — semantic match on the affected component (e.g. "database failover replication lag").
+3. `exec("grep -rln <subsystem-keyword> postmortems/")` — exact-term sweep for the service, the error, the mechanism.
+4. `exec("cat postmortems/<candidate>.md")` on the 1–3 closest matches — read their Root cause and Action items.
+
+**If this is a repeat of a class already documented, that is the most important finding in the entire document — and it belongs in the Summary, not buried in Related.** A recurrence means a prior action item did not land, or landed and did not prevent recurrence. State it in the first two sentences: "This is the third connection-pool exhaustion incident in the payments service (see [2024-01-11](./postmortems/2024-01-11-payments-pool.md), [2024-03-02](./postmortems/2024-03-02-payments-pool.md)); the action item from the second was never completed." Repeat classes are where postmortems earn their keep — surface them loudly.
+
+---
+
+## Step 3 — Create the postmortem from the template
+
+```
+write({ document: { path: "postmortems/YYYY-MM-DD-name.md", template: "postmortem" } })
+```
+
+- **The date is the incident date, not today's.** If the outage was 2024-03-02, the filename is `postmortems/2024-03-02-name.md` even if you write it a week later.
+- `name` is a short kebab slug of the affected system and failure: `payments-pool-exhaustion`, `auth-cert-expiry`, `search-index-corruption`.
+- The `postmortem` template scaffolds the SRE shape: Summary / Timeline / Root cause / What went well / Action items. Fill each in the steps below; do not invent a different structure.
+
+---
+
+## Step 4 — Summary: impact first, cause second
+
+The Summary is read by people who will never read the rest. Write it for the org, not for the on-call engineer.
+
+- **Lead with user-visible impact:** who was affected, how, and for how long. "For 47 minutes, roughly 12% of checkout attempts failed with a 500." Not "the connection pool saturated."
+- **Then one sentence of cause,** plain: "A config change halved the pool size while traffic was at peak; the pool exhausted and requests queued past timeout."
+- **If Step 2 found a repeat class, it goes here** (see Step 2).
+
+A summary that leads with the technology ("the connection pool saturated at 14:03") and buries the impact is written for engineers, not for the organization that needs to weigh the incident. Impact is the currency; state it first and in human terms.
+
+---
+
+## Step 5 — Timeline: timestamped, sourced, with the detection gap made explicit
+
+Reconstruct the incident chronologically. Every entry: a timestamp **with time zone**, what happened, and the evidence it came from.
+
+```
+- 13:52 UTC — Config change #4821 merged, halving `pool.max` from 200 to 100. (deploy log, PR #4821)
+- 14:03 UTC — Checkout error rate crosses 5%. (Grafana, checkout-errors panel)
+- 14:19 UTC — First page fires to on-call. (PagerDuty incident #9917)
+- 14:26 UTC — On-call acknowledges, begins investigating a suspected upstream issue. (incident channel)
+- 14:41 UTC — Config change identified as cause; rollback initiated. (incident channel)
+- 14:50 UTC — Error rate returns to baseline. (Grafana)
+```
+
+- **Call out detection time and mitigation time explicitly.** Mark the entry where the incident began, where it was *detected*, and where it was *mitigated*.
+- **The gap between incident start and detection is usually the most actionable number in the document.** Here: onset 14:03, first page 14:19 — sixteen minutes blind. Name that gap in prose right after the timeline: "Detection lagged onset by 16 minutes; there was no alert on checkout error rate, only on host CPU." That sentence is often the source of the highest-leverage action item.
+- Keep entries factual and sourced. Analysis goes in Root cause, not here.
+
+---
+
+## Step 6 — Trigger vs root cause vs symptom
+
+Give the reader the three definitions, then separate them cleanly. Conflating them is the most common way a postmortem produces a shallow fix.
+
+- **Symptom** — what was observed. "Checkout requests returned 500s; the pool showed zero free connections." The symptom is real but it is not the cause; fixing the symptom (restart, scale up) ends the incident without preventing the next one.
+- **Trigger** — the specific thing that set it off. "Config change #4821 halved the pool size at peak traffic." The trigger is necessary to the story but rarely the whole cause.
+- **Root cause** — the condition that made the trigger *sufficient* to cause the outage. Not "a bad config was pushed" — ask what made a bad config *pushable to production at peak with no guard*. The root cause is usually a missing safeguard, not the triggering action.
+
+**Push past the first plausible cause.** If your answer is "someone pushed a bad config," you have named the trigger and stopped. Keep going: What allowed an unreviewed config to reach production? Why was there no validation on pool-size bounds? Why did no canary catch it? Techniques like "five whys" help you keep asking — but they are a prompt, not a proof, and they tend to walk you down a single chain when reality had several. Most incidents have **several contributing factors and one or two root causes**, not a single linear chain. Name the one or two conditions that, if they had not held, the trigger would have been harmless.
+
+---
+
+## Step 7 — Contributing factors
+
+The conditions that widened the blast radius, delayed detection, or slowed recovery. These are not the root cause but they are why the incident was as bad as it was — and each is usually its own action item.
+
+Look specifically for:
+
+- **Missing or misrouted alerts** — the detection gap from Step 5 almost always lands here.
+- **Absent or stale runbook** — no documented recovery path, so the on-call improvised. Check `guides/` and its `last_verified` dates.
+- **Unclear ownership** — nobody knew who owned the failing component, so acknowledgement lagged.
+- **A stale guide** — a runbook that said to do the thing that made it worse, or whose `last_verified` was long past.
+- **Compounding conditions** — peak traffic, a concurrent deploy freeze, a second on-call already paged.
+
+List each as a discrete factor. Vague "communication could have been better" is not a factor; "there was no owner mapping for the payments pool, so the first page went to the wrong team for 7 minutes" is.
+
+---
+
+## Step 8 — What went well (genuinely)
+
+This section is not filler and skipping it quietly is a failure mode. Something limited the damage; name it so the org preserves it.
+
+- What made detection or recovery faster than it could have been? A good dashboard, a fast rollback path, a clear escalation.
+- What held up under load? The circuit breaker that shed load cleanly, the read replica that absorbed traffic.
+- Which prior action item paid off here? If a previous postmortem's fix limited this incident, say so and link it — that is the strongest possible argument for funding action items.
+
+Write it honestly. If genuinely little went well, say that plainly rather than manufacturing praise — "recovery was slow and manual; the one thing that worked was that rollback was a single command." Preserving what worked is as much the point as fixing what didn't.
+
+---
+
+## Step 9 — Action items: owned, dated, verifiable
+
+An action item with no owner is a wish. Every item gets three things or it does not go in the list:
+
+- **An owner** — a role or team (blameless: "the payments team," not a person's name unless the person self-assigns).
+- **A due date** — a real date, not "soon."
+- **A verifiable done-condition** — something you could check and unambiguously call done. "Add an alert on checkout error rate >2% for 3 minutes, tested by triggering it in staging" — not "improve alerting."
+
+Classify each item by what it buys you:
+
+- **Prevention** — stops this exact recurrence (add pool-size validation to the config pipeline).
+- **Mitigation** — limits the damage next time it happens anyway (auto-shed load when the pool saturates).
+- **Detection** — finds it sooner (the missing error-rate alert from Step 5).
+
+A healthy postmortem has items across all three; a list that is all prevention often means the detection and mitigation gaps went unexamined.
+
+**Guide-shaped action items produce runbook stubs.** When an item is "write/fix the recovery runbook for X," don't just name it — stub it now:
+
+```
+write({ document: { path: "guides/db-pool-exhaustion-runbook.md", template: "runbook" } })
+```
+
+Pre-fill the stub with the **symptom** (how you'd recognize this again — "checkout 500s + pool free-connections at zero") and the **relevant timeline excerpt** (the rollback steps that actually worked, lifted from Step 5). Then link the stub from the action item: `- [ ] Payments team, by 2024-03-16: complete the [pool-exhaustion runbook](./guides/db-pool-exhaustion-runbook.md), verified by a tabletop dry-run.` The runbook carries `last_verified` frontmatter so it surfaces in review when it goes stale.
+
+---
+
+## Step 10 — Link and validate
+
+- Add a `## Related` section linking **every prior postmortem that shares a subsystem** (from Step 2), plus the `decisions/` and `specs/` implicated — the decision that set the config policy, the spec for the component that failed. `[2024-01-11 payments pool](./postmortems/2024-01-11-payments-pool.md)`, `[connection-pool sizing decision](./decisions/2023-11-04-pool-sizing.md)`.
+- Link the runbook stubs you created in Step 9 from their action items (done above) and from `## Related`.
+- Update the hub of any folder you touched if it has one (an `INDEX.md` in `postmortems/`) so the new incident shows up in the index — the preview becomes a live progress bar.
+- Validate: `links({ kind: "dead", sourceDocNames: ["postmortems/YYYY-MM-DD-name"] })` returns clean — fix or drop every dead link. Confirm frontmatter is complete and the Summary / Timeline / Root cause / What went well / Action items sections are all filled, none left as template placeholder.
+
+---
+
+## Step 11 — Recap
+
+Close in conversation with four things, tightly:
+
+1. **Impact** in one line, user-visible terms.
+2. **Root cause** in one sentence (the condition, not the trigger).
+3. **The single highest-leverage action item** — usually the one that closes the detection gap or the missing safeguard.
+4. **Whether this is a repeat class** — and if so, why the prior fix didn't hold.
+
+Then point at the file: `postmortems/YYYY-MM-DD-name.md` and any runbook stubs created.
+
+---
+
+## Non-goals
+
+- **Don't assign blame to people.** Systems and roles, never individuals. If a name is load-bearing to the story, the story is framed wrong — find the system affordance instead.
+- **Don't stop at the first plausible cause.** "A bad config was pushed" is a trigger. Keep asking what made the trigger sufficient until you reach a missing safeguard.
+- **Don't write action items you cannot verify.** No owner, no date, no checkable done-condition means it is a wish, not an action item. Leave it out or fix it.
+- **Don't quietly omit "what went well."** Skipping it loses the practices worth preserving. If little went well, say so honestly rather than dropping the section.
+- **Don't use a postmortem to relitigate a design decision.** A postmortem documents what happened and what to change operationally. Arguing that the architecture should have been different belongs in a proposal (`frame-a-proposal`) or a design review (`review-a-design`) — link to it from Related; don't fight it here.
+- **Don't fabricate the timeline.** No entry without a source you can point at; reconstructed-from-memory entries are labelled inline as such.

package/dist/assets/skills/packs/software-lifecycle/write-a-spec/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: open-knowledge-pack-software-lifecycle-write-a-spec
+description: "Scope a feature end to end and write an implementation spec under specs/ from an accepted proposal — current-system mapping, goals/non-goals, a Decision Log for one-way-door choices, a live Open Questions backlog, and a real migration + test plan. Read when asked to write a spec, scope this feature, turn this proposal into a spec, plan the implementation, or break this into tasks. Do NOT fire on frame a proposal or write the PRD (sibling frame-a-proposal — a PRD frames a change before it is accepted; this skill starts once one is), record a decision or write the ADR (record-a-decision), write a postmortem (write-a-postmortem), or review this design (review-a-design) — those are separate skills. Complements the platform open-knowledge skill; does not replace it."
+compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack software-lifecycle`."
+metadata:
+  pack: "software-lifecycle"
+  author: "Inkeep"
+  repository: "https://github.com/inkeep/open-knowledge"
+---
+# Write a spec — scope a feature and commit an implementation spec
+
+> This skill is pack guidance. The platform `open-knowledge` skill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers spec-writing craft on top.
+
+A spec is the contract between "we decided to build this" and "here is how it gets built." It is derived from an ACCEPTED proposal, maps the system that exists TODAY before proposing a change, and records its one-way-door choices in a Decision Log so the reasoning survives the author leaving. A spec that skips the current-system mapping, or resolves its open questions silently, is a liability — it reads authoritative while being unfounded.
+
+`specs/` uses a folder-per-spec shape: `specs/NNN-name/` holding `spec.md`, and (when the work is actually going to be built) `plan.md` + `tasks.md`. The pack ships all three templates. `status` on `spec.md` flows `draft → ... → shipped`.
+
+## Autonomy mode
+
+| Mode | Behavior | How entered |
+|---|---|---|
+| **Supervised** (default) | STOP at the Step 2 scoping gate for user confirmation of Goals / Non-goals / change shape. Route open decisions interactively. | Default when a user drives the session. |
+| **Headless** | Auto-confirm the scoping proposal after presenting it; auto-select routing decisions. All other gates (parent-proposal check, current-system mapping, Decision Log, validation, grounding) still enforced. | Explicit "don't wait for me", "just proceed", "run headless" — or non-interactive container environments. |
+
+In headless mode, propose the scope AND proceed immediately; record in the Decision Log that scope was auto-confirmed without user sign-off.
+
+---
+
+## Mandatory execution order
+
+**Hard gates — do NOT skip ahead.** If you find yourself about to write `## Design` before you have read the actual code the change touches, STOP — you skipped Step 1.
+
+0. **Find the parent proposal.** No accepted proposal behind a spec is a smell.
+1. **Map the CURRENT system.** Read real code + prior specs + guides. Write what exists today, with pointers.
+2. **Scoping STOP gate.** Propose Goals / Non-goals / change shape. In Supervised mode, WAIT.
+3. **Create the spec folder + `spec.md`** from the `spec` template; allocate `NNN` by listing, not guessing.
+4. **Fill Goals / Non-goals** — non-goals temporal, each with a reason.
+5. **Design** — options considered, one chosen, why; one-way doors flow to the Decision Log.
+6. **Decision Log** — append the section; each entry survives the author.
+7. **Open Questions** — a live backlog, each with its closing evidence and decider.
+8. **Migration + Test plan** — real states, real tiers, explicit gaps.
+9. **`plan.md` + `tasks.md`** — only when the spec is going to be built.
+10. **Link + validate** — backlinks, dead-links clean, frontmatter complete.
+11. **Recap** — and what would move it out of `draft`.
+
+---
+
+## Step 0: Find the parent proposal
+
+A spec implements a decision that was already made. Before scoping anything, find the accepted proposal it derives from.
+
+1. `exec("ls -A proposals/")` — surface the proposal set with frontmatter enrichment.
+2. `exec("ls -A decisions/")` — an accepted proposal often has a matching frozen record here.
+3. `search({ query: "<feature name or problem statement>" })` — semantic match across both folders when the name differs from the filename.
+4. For the 1-2 strongest candidates, `exec("cat proposals/0004-x.md")` — read the accepted design and its unresolved questions in full; those unresolved questions become your Open Questions seed.
+
+**Route on what you find:**
+
+- **Accepted proposal exists** → note its path; it becomes `parent_proposal:` in the spec frontmatter. Proceed to Step 1.
+- **Proposal exists but is not accepted** (`draft`, `fcp`, `rejected`) → STOP. A spec for an un-accepted proposal builds on sand. Surface this: "The proposal `<path>` is at `status: <x>`, not accepted. A spec should follow an accepted proposal. Want me to help get it accepted first, or proceed anyway?"
+- **No proposal at all** → say so plainly: "There's no accepted proposal behind this feature. Specs derive from proposals — the proposal is where we argue *whether* to build; the spec is *how*. I can frame a proposal first (that's the `frame-a-proposal` skill), or, if you acknowledge the risk, proceed straight to a spec and record that we skipped the proposal." If the user opts to proceed, record that choice in the Decision Log (Step 6) with its rationale. Do not silently skip it.
+
+**HARD GATE:** do not create `spec.md` until the parent-proposal question is resolved one way or the other and, if skipped, acknowledged by the user.
+
+---
+
+## Step 1: Map the CURRENT system before designing the change
+
+The most common spec failure is designing against an imagined system. You cannot write a sound `## Design` or a real `## Migration` without knowing what the running system does today.
+
+**Read the code that exists — with native host tools.** Source code (`.ts`, `.py`, config, schema) lives OUTSIDE the knowledge base, so read it with the host's native file tools (Read / Grep / Glob), not OpenKnowledge verbs. Trace the actual flow end to end: the entry points, the modules the change will touch, the data shapes, the call chain across boundaries.
+
+**Read the knowledge base with OpenKnowledge verbs.** Prior specs and guides ARE in-scope markdown:
+
+- `exec("ls -A specs/")` — see what's been specced before; a sibling spec may already map the same subsystem.
+- `exec("cat specs/003-x/spec.md")` — read the closest prior spec's Design + Migration for the shape and the pointers.
+- `exec("ls -A guides/")` then `exec("cat guides/<runbook>.md")` — runbooks describe operational reality the code alone won't tell you.
+- `search({ query: "<subsystem name>" })` — surface adjacent decisions and postmortems that constrain the design.
+
+**Write what exists today into the spec's Design section as a "Current system" subsection first**, with file/module pointers (`src/foo/bar.ts`, the `handleX` function, the `widgets` table). Concrete pointers are what make the spec verifiable and let a reviewer check your map against the code.
+
+**HARD GATE:** do not draft the proposed `## Design` until the current-system map is written with real pointers. If you cannot point at where a behavior lives today, you do not yet understand it well enough to change it.
+
+---
+
+## Step 2: Scoping STOP gate
+
+Before writing the spec body, propose the scope and get confirmation. Getting Goals / Non-goals wrong is expensive to unwind after the spec is drafted.
+
+Present this to the user:
+
+```
+## Proposed scope
+
+**Parent proposal:** [path — or "none; proceeding without one per your acknowledgement"]
+
+**Goals** (what this spec delivers):
+1. [Goal — an observable capability or change]
+2. ...
+
+**Non-goals** (explicitly out of THIS spec, and why):
+1. [Thing] — deferred because [reason]
+2. ...
+
+**Shape of the change:** [2-4 sentences: the approach at a high level, and which modules from the Step 1 map it touches]
+
+**Open questions I already see:** [1-3 — the ones that will gate the design]
+```
+
+**Supervised mode:** STOP and WAIT for confirmation. Do not create the spec folder until the user confirms or adjusts.
+
+**Headless mode:** present the scope AND proceed; note the auto-confirmation in the Decision Log.
+
+Scoping discipline:
+- If the feature is vague, narrow it here, not in the Design. "Which surfaces? For whom? What's explicitly deferred?"
+- Name the beneficiary of each goal — a goal with no one who benefits is scope creep.
+- Do not invent requirements the proposal never established (see Non-goals for this skill). If a goal isn't traceable to the parent proposal, flag it and ask.
+
+---
+
+## Step 3: Create the spec folder + `spec.md`
+
+Allocate the next `NNN` by **listing, not guessing**:
+
+1. `exec("ls -A specs/")` — read the existing `NNN-name/` folders. Take the highest `NNN`, add one, zero-pad to the existing width (`003` → `004`).
+2. Choose a short kebab-case name from the feature: `specs/004-payment-retries/`.
+3. Create the spec:
+
+```
+write({ document: { path: "specs/004-payment-retries/spec.md", template: "spec" } })
+```
+
+The `spec` template ships frontmatter and these H2 sections in order: `## Goals`, `## Non-goals`, `## Design`, `## Migration`, `## Test plan`. Fill the frontmatter now:
+
+```yaml
+type: spec
+description: "<one line: what this spec delivers>"
+status: draft
+owner: <user>
+target_release:
+created: <today YYYY-MM-DD>
+parent_proposal: ./proposals/0004-payment-retries.md   # or note the skip
+tags: [spec]
+```
+
+Set `parent_proposal:` to the relative markdown path from Step 0. Leave `target_release:` blank until the plan exists.
+
+---
+
+## Step 4: Fill Goals and Non-goals
+
+Edit the `## Goals` and `## Non-goals` sections via `edit({ ... })`.
+
+**Goals** — each an observable outcome, not an implementation detail. "Failed payments retry with backoff and surface a final status" is a goal; "add a `retryCount` column" is a design choice. Tie each goal to the beneficiary and, where possible, to the parent proposal's motivation.
+
+**Non-goals are TEMPORAL, not eternal.** Frame each as "not in THIS spec" with the reason it's deferred — never as "we will never do this." "Multi-currency retries — deferred; the retry engine is currency-agnostic and multi-currency is its own proposal" tells a future reader the door is open and why it's closed for now. "We don't support multi-currency" reads as a permanent product stance the spec has no authority to make. Every non-goal carries its *why*.
+
+---
+
+## Step 5: Design
+
+Edit `## Design`. It has two layers, in order:
+
+1. **Current system** (from Step 1) — what exists today, with file/module pointers. Keep this; it is what makes the proposed change legible.
+2. **Proposed change** — the options you considered, the one you chose, and why.
+
+For each meaningful design fork, write: the options on the table, the one chosen, and the reasoning. Name the trade-off you accepted. A design that presents only the chosen option hides the fact that a choice was made — and hides it from the reviewer whose job is to pressure-test it.
+
+**Every one-way-door choice goes to the Decision Log (Step 6).** A one-way door is a decision that is expensive or impossible to reverse once code ships on it: a wire format, a schema migration that drops data, a public API shape, a security boundary. Reversible choices (an internal helper name, a log level) do not need a log entry — keep the log to decisions that will cost real money to undo.
+
+---
+
+## Step 6: Decision Log
+
+The `spec` template does NOT ship a Decision Log — **you append it.** Add an `## Decision Log` section to `spec.md` after `## Test plan`. This is the single most valuable artifact in the spec: it is what a new owner reads to understand why the system is shaped the way it is, without having to re-derive it or ask someone who has left.
+
+Each entry is a short block:
+
+```markdown
+### DL-1: <the question, as a question>
+
+- **Options:** A [...], B [...], C [...]
+- **Choice:** B
+- **Rationale:** [why B beat A and C — the trade-off accepted, the evidence]
+- **Date:** YYYY-MM-DD
+- **Reverses if:** [what new fact or condition would force revisiting this]
+```
+
+Discipline:
+- One entry per one-way-door choice from Step 5, plus any process decision (e.g. "proceeded without a parent proposal per the user's acknowledgement on <date>").
+- The `Reverses if` line is not optional — a decision with no stated reversal condition can never be re-examined honestly.
+- This log is scoped to THIS spec. It is not the project's decision record. Recording an architecture decision in `decisions/` is the sibling `record-a-decision` skill's job; do not write ADRs here.
+
+---
+
+## Step 7: Open Questions
+
+A spec ships with its open questions MARKED, not silently resolved. Guessing at an answer and writing it as settled is how a spec misleads everyone downstream.
+
+Append an `## Open Questions` section (the template does not ship one). Keep it as a live backlog:
+
+```markdown
+### OQ-1: <the unresolved question>
+
+- **Blocks:** [which goal / design decision this gates, or "nothing — nice to know"]
+- **Closed by:** [the evidence that would resolve it — a benchmark, a load test, a product call, a spike]
+- **Decider:** [who has authority to close it — a role, not a name that will rot]
+- **Status:** open
+```
+
+Discipline:
+- If a question blocks a Decision Log entry, say so in both places — the log entry stays provisional until the question closes.
+- Prefer "we don't know yet, here's how we'd find out" over a confident guess. The boundary of what you know is information; a fabricated answer is a hazard.
+- As questions close during the spec's life, flip `Status: open` to `resolved → DL-N` and move the resolution into the Decision Log — don't just delete the question.
+
+---
+
+## Step 8: Migration and Test plan
+
+Both real, not decorative. A migration section that says "migrate the data" and a test plan that says "add tests" are worse than nothing — they signal coverage that doesn't exist.
+
+**`## Migration`** — name the STATES a live system passes through, in order, and what is true at each. A running system does not teleport from old to new; it lives in intermediate states where both must work:
+
+- The states, e.g.: (1) new code deployed, feature flag off, old path live. (2) backfill runs, both schemas readable. (3) flag on for a cohort, dual-write. (4) flag on globally. (5) old path + old column removed.
+- What is reversible at each state and where the point of no return is (link that point to its Decision Log entry).
+- Data at rest: what gets backfilled, what gets dropped, whether the drop is recoverable.
+- If the change needs no migration (net-new, no live data, no deployed callers), say so explicitly and why — don't leave the section empty.
+
+**`## Test plan`** — name WHAT is verified and at WHICH tier, and explicitly what is NOT verifiable and why:
+
+- Per goal: the tier that proves it — unit (a pure function's edges), integration (a component against its real collaborators), end-to-end (the user-visible flow), contract (a boundary both sides must honor).
+- The failure modes worth a test, not just the happy path — the retry that exhausts, the migration that half-completes, the concurrent write.
+- **What cannot be verified before ship, and why** — a production-only load characteristic, a third-party behavior you can't stage, a race that only manifests under real traffic. Naming the gap is what lets the reviewer decide whether it's acceptable; hiding it is how the gap becomes an incident.
+
+---
+
+## Step 9: `plan.md` and `tasks.md`
+
+**Only when the spec is actually going to be built.** A spec at `status: draft` that may not be implemented does not need these yet — creating them early produces stale scaffolding. Create them when the spec is greenlit for implementation.
+
+```
+write({ document: { path: "specs/004-payment-retries/plan.md",  template: "spec-plan"  } })
+write({ document: { path: "specs/004-payment-retries/tasks.md", template: "spec-tasks" } })
+```
+
+Set `parent_spec: ./spec.md` in both frontmatter blocks.
+
+**`plan.md`** (`## Approach`, `## Phases`, `## Risks + unknowns`, `## Dependencies`, `## Rollout`) — the how-to-build sequenced into phases. `Risks + unknowns` pulls from the Open Questions that block implementation; `Rollout` mirrors the Migration states.
+
+**`tasks.md`** (`## Tasks` checklist, `## Done when`, `## Out of scope`) — the work broken down. Two rules:
+- **Ordered by dependency.** A task that depends on another comes after it. The reader should be able to work top to bottom.
+- **Each task independently verifiable.** "Add retry backoff to the payment worker — verified by the exhaustion integration test" is a task; "improve reliability" is not. If you can't state how a task is checked, it's not decomposed enough.
+
+`## Done when` restates the spec's Goals as the completion bar. `## Out of scope` mirrors the Non-goals.
+
+---
+
+## Step 10: Link and validate
+
+Specs that don't link back are islands. Wire the spec into the graph and prove it's clean:
+
+- **Backlink the parent proposal** inline in the spec body: `derived from [Payment retries proposal](./proposals/0004-payment-retries.md)`. Plain markdown relative link — never backticked, never an HTML anchor.
+- **Link every decision the spec depends on** — if the design rests on a frozen record in `decisions/`, link it where it's relied upon.
+- Update the parent proposal (and any hub) to link forward to this spec, so the spec is discoverable via backlinks. `links({ kind: "backlinks", ... })` to confirm the reverse edge registered.
+- `links({ kind: "dead", sourceDocNames: ["specs/004-payment-retries/spec"] })` — returns clean, zero dead links. Fix or remove every one.
+- Frontmatter complete: `type`, `description`, `status`, `owner`, `parent_proposal`, `created`, `tags` all present.
+
+---
+
+## Step 11: Recap
+
+Close the loop with the user:
+
+```
+## Recap
+
+- Spec at specs/004-payment-retries/spec.md, status: draft
+- Derived from [proposal] (or: proceeding without one, logged as DL-N)
+- N goals, M non-goals (all temporal, with reasons)
+- Decision Log: K one-way-door choices recorded
+- Open Questions: J open — [name the ones that block the design]
+- Migration: [one line] · Test plan: [what's covered / what can't be]
+
+**To move out of `draft`:** [the specific things — usually: close the design-blocking open questions, get the owner's sign-off, and create plan.md + tasks.md once greenlit for build]
+```
+
+State plainly what is still open. A spec's honesty about its own gaps is what makes it trustworthy.
+
+---
+
+## Non-goals
+
+- **Don't invent requirements the proposal didn't establish.** The spec is *how*, not a second bite at *whether*. A goal with no root in the parent proposal is scope creep — flag it, don't smuggle it in.
+- **Don't record decisions in `decisions/`.** That's the sibling `record-a-decision` skill. The spec's Decision Log is scoped to THIS spec's one-way doors; it is not the project's ADR record.
+- **Don't skip the current-system mapping.** Designing against an imagined system is the top failure mode. No `## Design` before Step 1's map with real pointers.
+- **Don't mark `shipped` before the work ships.** `status` reflects reality. A spec is `draft` until built, and only `shipped` once the code is live — never aspirationally.
+- **Don't write the postmortem.** If the shipped feature breaks, the incident write-up is the `write-a-postmortem` skill's job, not an addendum here.
+- **Don't silently resolve Open Questions.** A marked open question is information; a fabricated answer is a hazard. Ship the spec with its unknowns visible.

package/dist/assets/skills/packs/worldbuilding/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: open-knowledge-pack-worldbuilding
-version: "0.18.0"
-description: "How to work in a Worldbuilding project (the `worldbuilding` starter pack): a fiction encyclopedia of characters, settings, themes, factions, and lore. Read when the project has these folders. Carries the auto-stub and consistency behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it."
+description: "How to work in a Worldbuilding project (the `worldbuilding` starter pack): a fiction encyclopedia of characters, settings, themes, factions, and lore. Read when the project has these folders, OR when asked to add a character, setting, faction, or piece of lore, or to check the world for internal consistency. Carries the auto-stub and consistency behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack worldbuilding`."
 metadata:
   pack: "worldbuilding"
@@ -12,7 +11,7 @@ metadata:
 
 This project is a fiction encyclopedia. The graph is the product: characters, settings, themes, factions, and lore that link to each other. The agent's main jobs are auto-stubbing new entities as they're mentioned and flagging contradictions. This skill holds those behaviors so templates and folder descriptions stay clean.
 
-> Pack guidance. The platform `open-knowledge` skill still governs every markdown operation.
+> This skill is pack guidance. The platform `open-knowledge` skill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers the worldbuilding conventions on top.
 
 ## Folders
 

package/dist/assets/skills/packs/writing-pipeline/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: open-knowledge-pack-writing-pipeline
-version: "0.18.0"
-description: "How to work in a Writing Pipeline project (the `writing-pipeline` starter pack): a three-stage drafting flow, ideas → drafts → published. Read when the project has these folders. Carries the stage flow and review behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it."
+description: "How to work in a Writing Pipeline project (the `writing-pipeline` starter pack): a three-stage drafting flow, ideas → drafts → published. Read when the project has these folders, OR when asked to capture an idea, start or revise a draft, review a piece before it ships, or publish it. Carries the stage flow and review behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack writing-pipeline`."
 metadata:
   pack: "writing-pipeline"
@@ -10,7 +9,10 @@ metadata:
 ---
 # Writing Pipeline pack — how to work here
 
-A lean three-stage flow for short-to-medium-form writing (essays, newsletters, blog posts):
+A lean three-stage flow for short-to-medium-form writing (essays, newsletters, blog posts).
+
+> This skill is pack guidance. The platform `open-knowledge` skill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers the drafting flow on top.
+
 
 ```
 ideas/      one-line premises, captured before they fade