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

package/dist/assets/skills/packs/software-lifecycle/frame-a-proposal/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: open-knowledge-pack-software-lifecycle-frame-a-proposal
+description: "Frame a new design proposal (RFC-shape) under proposals/ — problem before solution, named beneficiary and observable change, real alternatives, honest drawbacks, and a live open-questions backlog. Read when asked to frame a proposal, write an RFC, propose a design, pitch a change, draft a PRD-style design doc, or open a design proposal for review. Do NOT read to record a decision after it is accepted (use record-a-decision), to write an implementation spec (use write-a-spec), to write a postmortem (use write-a-postmortem), or to review or critique an existing design (use review-a-design)."
+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"
+---
+
+# Frame a proposal — turn a problem into a reviewable RFC
+
+The platform `open-knowledge` skill still governs every markdown operation here (reads via `exec`/`search`, writes via `write`/`edit`, links as plain relative markdown, never native Read/Edit/Grep/`cat` on in-scope files). This skill layers proposal-authoring craft on top: it decides *what a good proposal contains and in what order you earn each section*.
+
+A proposal in `proposals/` is a design argument, not a decision and not a plan. It exists to force a **choice** among options and to give reviewers enough to disagree with. Filename is `0001-feature-name.md` — a zero-padded 4-digit sequence plus a kebab title. Status flows `draft → fcp → accepted/rejected` (fcp = final comment period). Acceptance graduates the proposal to a record in `decisions/` — that is a *separate*, human act and a *separate* skill.
+
+The failure this skill exists to prevent: an agent jumping to `## Design` before anyone agrees what the problem is, padding `## Alternatives` with strawmen, and leaving `## Drawbacks` empty. Each step below has a gate that blocks that.
+
+---
+
+## Mandatory execution order
+
+**Hard gates — do NOT skip ahead.** If you are about to draft `## Design` and you have not passed the Step 1 framing gate, STOP — you skipped a gate. The whole point of a proposal is that the problem is agreed before the solution is written.
+
+0. **Scan prior art** — what already exists on this subsystem, in `proposals/` and `decisions/`.
+1. **Frame the problem — STOP gate.** Name beneficiary, observable change, forced decision. Get confirmation before any solution text.
+2. **Allocate the sequence number and create from the `proposal` template.**
+3. **Motivation** — problem, evidence, who is hurt today, cost of doing nothing, and explicit non-goals.
+4. **Design** — the proposal at an altitude a reader can disagree with.
+5. **Alternatives** — at least two real ones, each with why-not.
+6. **Drawbacks** — the honest cost.
+7. **Unresolved questions** — a live backlog, each with a resolver and resolving evidence.
+8. **Link + validate.**
+9. **Recap + what advancing to `fcp` would require.**
+
+Create workflow tasks for steps 0–9 in your host's task system if it has one — they make a skipped gate visible mid-session.
+
+---
+
+## Step 0: Scan prior art
+
+Before framing anything, find out what the knowledge base already decided or proposed about this subsystem. A proposal that silently re-litigates an accepted decision is dead on arrival; a proposal that cites it and explains why the decision should be revisited is legitimate.
+
+- `search({ query: "<subsystem or problem keywords>" })` — semantic, catches synonyms.
+- `exec("ls -A proposals/")` and `exec("ls -A decisions/")` — see the sequence space and what has landed.
+- `exec("grep -rln <keyword> proposals/ decisions/")` — pinpoint files that name the same subsystem.
+- For the 1–3 most relevant hits, `exec("cat proposals/0003-x.md")` to read the full doc plus its backlinks.
+
+Classify what you find, and carry it into the draft:
+
+| Found | Do this |
+|---|---|
+| An **accepted decision** covers this area | The new proposal MUST cite it (a markdown link into `decisions/`) and, in Motivation, say what changed that reopens it. If nothing changed, tell the user this may not need a proposal at all. |
+| A **draft/fcp proposal** overlaps | Offer to extend or supersede it rather than open a near-duplicate. Two overlapping proposals split the review. |
+| **Nothing** | Proceed clean. |
+
+---
+
+## Step 1: Frame the problem — STOP gate
+
+This is the gate that makes the difference between an RFC and a pile of solution text. **Do NOT draft `## Design`, and do NOT create the file, until the user confirms the framing.**
+
+Produce and return exactly this, then STOP and wait:
+
+```
+## Framing (confirm before I draft)
+
+**Beneficiary:** who is worse off today and will be better off if this ships. A named role or user, not "the system" or "us".
+
+**Observable change:** the concrete, checkable difference they will see. "X drops from N to M", "Y becomes possible", "Z stops happening". Not "improve", not "streamline".
+
+**Forced decision:** the one question this proposal makes reviewers answer. If accepting it doesn't commit anyone to anything, it is a report, not a proposal.
+
+**Rough shape:** one sentence on the direction — enough to know we're framing the right problem, not the design itself.
+```
+
+Discipline:
+
+- If you cannot name a beneficiary distinct from "the team," the problem isn't framed. Push back before drafting.
+- "Observable change" is falsifiable or it isn't done. If you can't state how you'd check it, you're describing an activity, not an outcome.
+- Vague trigger ("we should have a proposal for the cache")? Narrow it: for whom, forced by what decision, changing what they observe.
+- In an explicitly headless/non-interactive run, state the framing AND proceed, but write the three fields verbatim into Motivation so a reviewer can reject the framing itself.
+
+---
+
+## Step 2: Allocate the number and create from template
+
+**List, don't guess, the sequence.** `exec("ls -A proposals/")`, take the highest existing `NNNN`, add one, zero-pad to four digits. Guessing collides the moment two proposals are drafted the same week.
+
+Filename: `NNNN-kebab-title.md` (`0007-async-export-pipeline.md`). Create it from the template — this is the only way the `## Motivation → ## Design → ## Drawbacks → ## Alternatives → ## Unresolved questions` skeleton and the frontmatter arrive correctly:
+
+```
+write({ document: { path: "proposals/0007-async-export-pipeline.md", template: "proposal" } })
+```
+
+The template stamps this frontmatter — fill it, don't retype it by hand:
+
+```yaml
+type: proposal
+description: "..."     # one line: the forced decision, not the feature name
+status: draft          # stays draft until a human advances it — see Non-goals
+authors: [<user>]
+created: YYYY-MM-DD
+tags: [proposal]
+```
+
+Set `description` to the decision the proposal forces, in one line — it is what a reader sees in a listing.
+
+---
+
+## Step 3: Motivation
+
+Fill `## Motivation` by `edit`-ing the created doc. This section has to stand on its own: a reader who disagrees here will never read your Design, and that's correct.
+
+- **The problem**, stated as the beneficiary experiences it — not as the absence of your solution. "Exports over 100MB time out and users lose the job" beats "we have no async export pipeline."
+- **Evidence** it is real: a metric, a repeated report, a concrete incident. A proposal motivated only by "it would be nice" is under-motivated; say so to the user and go find one signal.
+- **Who is hurt today**, named (the Step 1 beneficiary), and how often.
+- **Cost of doing nothing** — the status-quo baseline every alternative, including "reject this," is measured against. If doing nothing is genuinely fine, the proposal may not need to exist.
+- **Non-goals — explicitly.** List what this proposal deliberately does *not* address. Non-goals are how you keep a proposal reviewable; an unbounded proposal can't be accepted because no one can tell what they're agreeing to. Put them under a clear `### Non-goals` line inside Motivation.
+
+---
+
+## Step 4: Design
+
+Fill `## Design` with the actual proposal, pitched **at the altitude where a reader could disagree with it**. Too low (every function signature) and reviewers rubber-stamp a design they didn't evaluate; too high ("we'll make it faster") and there's nothing to accept. The target: a competent reader could read this section and say "no, I'd do it differently, because…"
+
+- Describe the mechanism, the shape of the change, and the key interfaces or contracts it introduces or alters.
+- Make the load-bearing choices explicit. If the design rests on one decision (a data model, a boundary, a sequencing), name it — that decision is usually what the whole proposal is really about.
+- State how the Step 1 observable change is achieved. Tie the design back to the beneficiary.
+- Link related specs, guides, and the decisions you're building on or revisiting, as plain relative markdown: `[the export boundary decision](./decisions/0004-export-boundary.md)`.
+- Keep implementation minutiae out — that granularity is the spec's job (a sibling skill), not the proposal's.
+
+---
+
+## Step 5: Alternatives
+
+Fill `## Alternatives` with **at least two real options**, each carrying **why it was not chosen**. Include the honest ones you'd have picked on a different day, plus "do nothing" if it's live.
+
+Structure each:
+
+```
+### Alternative: <name>
+What it is — one honest paragraph, argued at its best.
+Why not — the specific tradeoff that lost, versus the proposed design.
+```
+
+Discipline:
+
+- **Strawmen are a red flag — say so.** An Alternatives section where every option is obviously worse means the author didn't consider real ones, and reviewers will (correctly) distrust the whole proposal. If you can't state an alternative's genuine appeal, you haven't understood it well enough to reject it.
+- "Do nothing" is a first-class alternative. Its "why not" is the Step 3 cost-of-doing-nothing.
+- The right number is usually two to four. One means you're not proposing, you're announcing.
+
+---
+
+## Step 6: Drawbacks
+
+Fill `## Drawbacks` with the honest cost of the proposed design — not the alternatives', its own.
+
+- **A proposal with no drawbacks is under-examined, not perfect.** Every real design gives something up: complexity, a migration, a new failure mode, a maintenance burden, a closed door. Name them.
+- Be specific about who pays and when — the cost may land on a different party than the beneficiary, and reviewers need to see that tradeoff.
+- If you genuinely believe a drawback is acceptable, say why here rather than hiding it. A stated-and-accepted drawback is stronger than a silent one a reviewer discovers.
+
+---
+
+## Step 7: Unresolved questions
+
+Fill `## Unresolved questions` as a **live backlog**, not a disclaimer. Each entry keeps a real open question visible instead of burying it in confident prose.
+
+For each question:
+
+```
+- **<question>** — What would resolve it: <the evidence, experiment, or measurement>. Who decides: <role or person>.
+```
+
+- Every question names **what evidence would resolve it** and **who decides**. A question with neither is just an anxiety; either sharpen it or drop it.
+- Questions that block acceptance belong here explicitly — they are the agenda for the `fcp` period.
+- It is correct for this section to be non-empty at `draft`. Hiding uncertainty to look finished is the failure mode; an honest open-questions list is what makes the proposal safe to review.
+
+---
+
+## Step 8: Link + validate
+
+Run before you tell the user it's ready:
+
+- Every referenced decision, spec, or guide is a plain markdown relative link (`[text](./decisions/0004-x.md)`), never backticked, never an HTML anchor.
+- Add backlinks from 1–2 closely related docs so the proposal is discoverable — the accepted decision it revisits, a related spec, the relevant guide. `links({ kind: "backlinks", ... })` to see what already points where.
+- `links({ kind: "dead", sourceDocNames: ["proposals/0007-async-export-pipeline"] })` returns clean — fix or remove every dead link.
+- Frontmatter complete: `type: proposal`, a one-line `description`, `status: draft`, `authors`, `created`, `tags: [proposal]`.
+- All five H2 sections present and non-empty: `## Motivation`, `## Design`, `## Drawbacks`, `## Alternatives`, `## Unresolved questions`. An empty Drawbacks or a strawman Alternatives fails this check even though the section technically exists.
+- `status` is still `draft`. You do not advance it — see Non-goals.
+
+---
+
+## Step 9: Recap + path to fcp
+
+Close with the user in conversation:
+
+```
+## Recap
+
+- Framed: <beneficiary> gets <observable change>; forces the decision <…>.
+- Proposal: proposals/NNNN-title.md (status: draft)
+- Alternatives weighed: <n>, chosen over them because <one line>.
+- Honest drawbacks: <the main one>.
+- Open questions still live: <count> — the fcp agenda.
+
+**To advance to `fcp`:** a human moves status draft → fcp and opens the final comment
+period. Acceptance (→ accepted, then a record in decisions/) is a human decision, not
+mine. If it's rejected, mark status: rejected and keep the doc — the reasoning is the value.
+```
+
+State plainly that advancing status and accepting the proposal are human acts. Your job ended at a well-framed, honestly-argued `draft`.
+
+---
+
+## Non-goals
+
+- **Don't record the decision.** Acceptance graduates a proposal to a record in `decisions/` — that's the sibling `record-a-decision` skill, run *after* a human accepts. This skill stops at `draft`.
+- **Don't write the implementation spec.** Design altitude, not build detail. The spec is `write-a-spec`.
+- **Don't mark a proposal `accepted` (or `fcp`) on your own authority.** Advancing status is a human act. Leave `status: draft`; offer the recap of what advancing would require.
+- **Don't skip the Step 1 framing gate.** Solution text before an agreed problem is the exact failure this skill exists to prevent. If you've drafted Design without a confirmed beneficiary and forced decision, you skipped the gate — back up.
+- **Don't pad Alternatives with strawmen or leave Drawbacks empty.** Both are tells that the proposal wasn't really examined. Reviewers read them as such.

package/dist/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: open-knowledge-pack-software-lifecycle-record-a-decision
+description: "Records an architecture decision as a Nygard/MADR-shaped ADR under decisions/ — capturing the context that forced the choice, the options weighed, the decision itself, and its consequences in both directions, plus the supersedes chain that keeps a decision log honest. Read when asked to record an architecture decision, write an ADR, log the decision we made, document why we chose X over Y, capture this decision for the record, or supersede an old decision with a new one. Do NOT read to frame a proposal or explore an idea not yet decided (frame-a-proposal), to write a spec or implementation plan (write-a-spec), to write an incident postmortem (write-a-postmortem), or to judge whether a design is sound (review-a-design). This skill records a decision already made; it does not make one."
+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"
+---
+
+# Record a decision — write an ADR under `decisions/`
+
+The platform `open-knowledge` skill still governs every markdown operation here (grounding, linking, the rule that OK's MCP tools own in-scope markdown); this skill layers ADR craft on top.
+
+An Architecture Decision Record is a small, dated, frozen document that captures **one** decision, the forces that made it necessary, and what the team now has to live with. The value compounds over years: a reader who joins in three years should understand not just what was decided but *why it was even a question*. ADRs are frozen once accepted — you never rewrite one to change your mind, you **supersede** it with a new record and leave the old one standing as history. That supersedes chain is what separates an honest decision log from a pile of stale opinions.
+
+Filenames are `NNNN-title.md` (zero-padded 4-digit sequence + kebab title). Status vocabulary: `proposed` / `accepted` / `deprecated` / `superseded`. Template id `decision`, body sections exactly `## Context`, `## Decision`, `## Consequences` in that order.
+
+---
+
+## Step 0 — Confirm a decision was actually MADE (HARD GATE)
+
+**An ADR records a decision; it does not make one.** Before anything else, establish that a choice has been settled.
+
+- If the user is still weighing options, comparing approaches, or asking "should we do X or Y?" — they do not have a decision yet. **Stop and route them to the `frame-a-proposal` skill.** A proposal is where options get explored and argued; an ADR is where the settled outcome gets recorded. Recording a decision the user has not made produces a fake record that misleads every future reader.
+- If the user says "we decided X" but you cannot tell *what lost* or *why*, ask one question: "What were the alternatives, and what made you pick this one?" An ADR with no rejected options is a press release, not a record.
+- If the thing in question is whether the design itself is sound — not the record of it — hand off to `review-a-design`. This skill assumes the decision is sound; it captures it.
+
+Do not proceed past this gate until the user has confirmed a specific decision. State it back to them in one sentence and get a nod.
+
+---
+
+## Step 1 — Scan for prior art (surface supersedes candidates BEFORE writing)
+
+A new ADR that silently contradicts an accepted one is how a decision log rots. Before allocating a number, find what already exists.
+
+1. `search({ query: "<subsystem or topic of the decision>" })` — semantic sweep for related decisions, proposals, and specs.
+2. `exec("ls -A decisions/")` — see the existing sequence and titles.
+3. `exec("grep -rln <subsystem-keyword> decisions/")` — find records touching the same subsystem, interface, or constraint.
+4. For each promising hit, `exec("cat decisions/NNNN-x.md")` — read its Decision and Status.
+
+Then classify and surface to the user **before writing**:
+
+- **Contradicts an accepted record** → this new decision reverses or replaces it. Flag the path as a `supersedes:` candidate: "This looks like it supersedes [0007-use-rest-api](./decisions/0007-use-rest-api.md), which is currently `accepted`. Confirm and I'll wire the chain in Step 7." Do not silently write a contradicting record.
+- **Extends without contradicting** → note the related record; you'll link it, not supersede it.
+- **Genuinely new** → proceed.
+
+If the decision graduated from an accepted proposal in `proposals/`, locate that proposal now (`exec("grep -rln <topic> proposals/")`) — you'll link it as the parent in Step 4.
+
+---
+
+## Step 2 — Allocate the next number and create from the template
+
+**Never guess the sequence number.** List the folder and take the next integer.
+
+1. `exec("ls -A decisions/")` — read the highest existing `NNNN`.
+2. Next number = highest + 1, zero-padded to 4 digits. First-ever decision is `0001`.
+3. Pick a short kebab title naming the decision, not the topic: `0012-adopt-event-sourcing-for-orders`, not `0012-orders`.
+4. Create it from the template:
+
+```
+write({ document: { path: "decisions/0012-adopt-event-sourcing-for-orders.md", template: "decision" } })
+```
+
+The template lays down the frontmatter scaffold and the three H2 sections. Fill the frontmatter now:
+
+```yaml
+type: decision
+description: "One line: the decision, active voice."
+status: proposed        # proposed until the deciders accept; then accepted
+date: YYYY-MM-DD        # today
+deciders: [<user>]      # who owns this decision
+supersedes: []          # fill in Step 7 if this replaces an earlier record
+tags: [decision]
+```
+
+Leave `status: proposed` while drafting. It becomes `accepted` only when the deciders sign off (Step 8) — an ADR that ships `accepted` before anyone agreed is backdating.
+
+---
+
+## Step 3 — Context: the forces at play (invest here)
+
+`## Context` is the section that ages best. Write it so a reader three years from now understands why this was even a question — no access to the meeting, the thread, or your memory. Cover:
+
+- **The state of the system** when the decision was forced — what exists, what's under strain.
+- **What changed** to make a choice necessary now rather than never. A new requirement, a scaling limit hit, a deprecated dependency, a deadline.
+- **The constraints** that bounded the options — team size, existing tech, latency budgets, compliance, a hard date.
+- **The forces in tension** — the reason this is a *decision* and not an obvious call. If there were no competing pressures, there'd be nothing to record.
+
+Write it neutrally and factually. Do not argue for the decision here — that's Step 4's job. Context describes the problem so completely that the Decision reads as one reasonable response to it. If a reader finishes Context and still can't see why a choice was needed, the section has failed; rewrite it.
+
+Ground every factual claim about the system in something checkable — link the proposal, a spec, or a prior decision rather than asserting from memory.
+
+---
+
+## Step 4 — Decision: active voice, one paragraph, unambiguous
+
+`## Decision` states what will be done, in the active voice, present or future tense: **"We will ..."** One clear paragraph. A reader must finish it knowing exactly what was chosen with zero ambiguity.
+
+Then, briefly:
+
+- **Name the options that were weighed and why the others lost.** Two or three sentences per rejected option is enough — "We considered X but it couldn't meet the latency budget; Y was simpler but locked us to a single vendor." This is the heart of the record; a decision with no visible alternatives is unverifiable.
+- **Link the parent proposal** if the decision graduated from one: "This decision accepts [0004-orders-rearchitecture-proposal](./proposals/0004-orders-rearchitecture-proposal.md)." Plain markdown relative link, never backticked, never an HTML anchor.
+
+Do not fold implementation detail into the Decision — *how* it gets built belongs in a spec, not the ADR. The Decision says what and why, not the migration steps.
+
+---
+
+## Step 5 — Consequences: both directions, honestly
+
+`## Consequences` records what the team now lives with — **good AND bad**. A Consequences section with only upside is a marketing document, not an ADR. Cover, in whatever grouping fits:
+
+- **What gets easier** — the wins that motivated the choice.
+- **What gets harder** — the costs, the new complexity, the thing that's now more awkward.
+- **What new obligation the team carries** — ongoing maintenance, a new skill to hire for, a dependency to track, an invariant someone must now uphold.
+- **What this forecloses** — options you can no longer take cheaply, doors this closes.
+- **Neutral consequences** — facts that are neither win nor loss but that a future reader needs.
+
+Force yourself to write at least one genuine negative and one new obligation. If you can't find any, you haven't thought hard enough — every real decision costs something. The negatives are the most valuable part of the record; they're what a future team checks when the decision starts to hurt.
+
+---
+
+## Step 6 — Soundness self-check (adversarial pass before committing)
+
+Read the draft as a skeptic who disagrees with the decision. Answer each honestly and fix what fails:
+
+- **One-way door or reversible?** Is the reversibility of this decision stated? A one-way door (hard or expensive to undo) must say so explicitly in Consequences — that's the single most important thing a future reader needs to know before they inherit it.
+- **Does Context actually motivate the Decision?** Or does the Decision arrive from nowhere, with forces in Context that don't point at it? If the two sections don't connect, one of them is wrong.
+- **Would a reader who disagrees find their objection addressed?** The strongest counter-argument should appear somewhere — in a rejected option or a named consequence. If the obvious objection is missing, add it.
+- **Is any consequence being hidden because it's inconvenient?** The cost you'd rather not write down is exactly the one that belongs in the record.
+
+If this pass reveals that the *design itself* is in question — not the quality of the record but whether the decision is right — stop and hand off to `review-a-design`. This skill records sound decisions; it is not the place to relitigate one.
+
+---
+
+## Step 7 — Supersedes chain (both directions or it's broken)
+
+If this record replaces an earlier one, the chain must be wired in **both** directions or the log lies from one side.
+
+1. **Forward, on the new record:** add the old path to `supersedes:` frontmatter.
+
+```
+edit({ document: { path: "decisions/0012-adopt-event-sourcing-for-orders.md",
+  frontmatter: { supersedes: ["decisions/0007-use-rest-api.md"] } } })
+```
+
+2. **Backward, on the old record:** flip its status and add a forward link so a reader landing on the old decision is sent to the new one.
+
+```
+edit({ document: { path: "decisions/0007-use-rest-api.md",
+  frontmatter: { status: "superseded" } } })
+```
+
+Then add a line near the top of the old record's Context (or a short `> Superseded by ...` note): `Superseded by [0012-adopt-event-sourcing-for-orders](./decisions/0012-adopt-event-sourcing-for-orders.md).`
+
+**Never edit the old record's Context, Decision, or Consequences prose.** ADRs are frozen — the old decision was true when it was made and stays on the record as history. You add the status flip and the forward pointer; you do not rewrite what it said. Both edits land, or the chain is broken in one direction and the log becomes untrustworthy.
+
+---
+
+## Step 8 — Link and validate
+
+- **Backlinks in:** ensure the parent proposal links forward to this decision, and any spec that *implements* this decision links back to it. `links({ kind: "backlinks", docName: "decisions/0012-adopt-event-sourcing-for-orders" })` to see who points here; add the missing ones so the record is discoverable.
+- **Dead links out:** `links({ kind: "dead", sourceDocNames: ["decisions/0012-adopt-event-sourcing-for-orders"] })` returns clean — zero dead links. Fix or remove every one; a broken link to a superseded record defeats the whole chain.
+- **Frontmatter complete:** `type`, `description`, `status`, `date`, `deciders`, `supersedes`, `tags` all present and correct.
+- **Status reflects reality:** if the deciders have accepted, flip `status: proposed` → `accepted`. If they haven't, leave it `proposed` and tell the user it's awaiting sign-off. Do not mark a decision `accepted` on the user's behalf.
+- **Body shape:** exactly `## Context`, `## Decision`, `## Consequences`, in order. No extra top-level sections — depth that doesn't fit these three belongs in a linked spec.
+
+---
+
+## Step 9 — Recap to the user
+
+Close in conversation, three things:
+
+1. **The decision in one sentence** — the "We will ..." line.
+2. **Its biggest consequence** — the one cost or obligation the team most needs to remember, especially if it's a one-way door.
+3. **Any record it superseded** — name the old ADR and confirm the chain is wired both ways.
+
+Then note whether `status` is `accepted` (deciders signed off) or `proposed` (awaiting sign-off), so the user knows what, if anything, is still open.
+
+---
+
+## Non-goals
+
+- **Don't decide on the user's behalf.** If no decision has been made, route to `frame-a-proposal`. This skill records; it does not choose.
+- **Don't rewrite an accepted record.** ADRs are frozen. To change a past decision, supersede it (Step 7) and leave the old one standing — never edit its Context/Decision/Consequences prose.
+- **Don't fold implementation detail into an ADR.** The migration plan, the API shape, the rollout steps belong in a spec (`write-a-spec`). The ADR captures what and why, not how.
+- **Don't record a decision that has no consequences section.** A record with only upside, or with no costs and no new obligations, isn't an ADR — it's marketing. Every real decision costs something; find it and write it down.
+- **Don't judge the soundness of the design here.** If the question is whether the decision is *right* rather than whether it's well-recorded, that's `review-a-design`.

package/dist/assets/skills/packs/software-lifecycle/review-a-design/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: open-knowledge-pack-software-lifecycle-review-a-design
+description: "Reviews whether a design is SOUND — solving the right problem, derived from its stated goals and constraints — and emits ranked, evidence-backed findings, not edits. Read when asked to 'review this design', 'is this design sound', 'pressure-test this proposal', 'do a design review', 'does this solve the right problem', 'poke holes in this spec', 'should we build this', or to critique a proposal / spec / ADR / architecture or product decision. Do NOT read when the user wants to AUTHOR one of these — routing a new proposal is frame-a-proposal, a spec is write-a-spec, a decision record is record-a-decision, a postmortem is write-a-postmortem. Do NOT read for code review of a diff, or to fact-check individual claims (that is a correctness pass, a different job)."
+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"
+---
+
+# Review a design — is it sound, not just complete
+
+The platform `open-knowledge` skill still governs every markdown operation here (reads via `exec`, writes via `write`/`edit`, links as plain relative markdown, MCP owns in-scope `.md`); this skill layers design-review craft on top of it.
+
+**Three reviews are not the same review, and only one is this skill's job.**
+
+- **Completeness review** asks: is every section filled in? (Are Drawbacks and Alternatives non-empty?)
+- **Correctness review** asks: are the individual claims true? (Does the benchmark really say 40ms? Is that API deprecated?)
+- **Soundness review** asks: *should this be built at all, and is this the design that follows from the stated goals and constraints?*
+
+You are doing the third. A proposal can be complete and factually correct and still be the wrong design — solving a symptom, chosen before its goals, engaging only strawman alternatives. Completeness and correctness are cheap to check and someone else's pass. Say this to the user up front if there's any ambiguity about what kind of review they want, then do soundness.
+
+You produce **findings, not edits.** The author decides what to change. Never rewrite the artifact under review unless explicitly asked.
+
+---
+
+## Step 0: Identify the artifact and read it — and what it inherits
+
+**HARD GATE: never review a design you have not read end to end, and never review it in isolation from the decisions it inherits.** A review of the first half is worse than no review — it spends the author's trust on partial understanding.
+
+1. Identify the type. It is one of:
+   - a **proposal** (`proposals/NNNN-name.md` — Motivation / Design / Drawbacks / Alternatives / Unresolved questions),
+   - a **spec** (`specs/NNN-name/spec.md` — Goals / Non-goals / Design / Migration / Test plan, with a `parent_proposal:`),
+   - a **decision** (`decisions/NNNN-title.md` — Context / Decision / Consequences, with a `supersedes:` chain), or
+   - an **in-flight choice with no document yet** (the user is deciding in conversation). This is a valid target — see Step 1.
+2. Read it whole: `exec("cat proposals/0003-feature.md")`.
+3. Read what it depends on. A design is only as sound as the ground it stands on:
+   - the **parent proposal** a spec links via `parent_proposal:`, and any proposal a decision implements;
+   - the **decisions it assumes** — `exec("grep -rln <subsystem-keyword> decisions/")`, then `cat` the relevant ones. A design that contradicts an accepted ADR without noting it is a finding by itself.
+   - the **prior postmortems in the same subsystem** — `exec("ls -A postmortems/")` and `search({ query: "<subsystem> failure" })`. A postmortem names a failure mode; a design that reintroduces it is your highest-value catch.
+   - **sibling proposals/decisions** it supersedes or overlaps — follow the `supersedes:` chain both directions.
+4. If the design references source code, read the code with the host's **native** tools (`Read`, `Grep`) — source is outside the knowledge base. In-scope markdown stays on `exec`/`search`.
+
+Do not proceed until you can name the goal, the constraints, and the prior decisions this design sits on top of.
+
+---
+
+## Step 1: Reconstruct the design's own argument — and show it back
+
+Before you critique anything, state the design's argument in your own words: **the goal it serves, the constraints it accepts, and why this design follows from them.** Show it to the user before Step 2.
+
+Why this gate exists:
+
+- If you can reconstruct it cleanly, the author gets a free confirmation that the intended reader understood it — often the most useful thing a review returns.
+- **If you cannot state the goal, the constraints, and why this design follows from them, the reviewable object does not exist yet — and that IS the finding.** Stop and report it: "I can't reconstruct why this design follows from its goals; here's where the chain breaks." Reviewing the surface of a design whose argument you can't state produces confident noise. Hand it back to the authoring skill to make the argument legible first.
+
+For an in-flight choice with no document, this step is where you force the argument into words for the first time. Frequently the act of reconstruction resolves the question without a single lens.
+
+---
+
+## Step 2: Run the soundness lenses
+
+Pass the design through each lens below. A lens is a named question plus the failure it catches — run the ones that bite for this artifact, skip the ones that plainly don't, and add any that earn their place. Do not mechanically fill all nine; a review that says the same shallow thing nine times teaches nothing.
+
+- **Problem lens** — *Is the stated problem the real problem, or a symptom of one upstream?* Whose problem is it, and what evidence says it hurts today (not hypothetically)? A design aimed at a symptom is unsound however elegant. Failure it catches: solving the wrong problem beautifully.
+- **Goal-derivation lens** — *Does the design follow from the stated goals, or were the goals reverse-engineered to justify a design chosen first?* Read the goals, then read the design cold: could you have predicted this design from these goals? If the design has a feature no goal demands, either the goal is unstated or the feature is scope. Failure it catches: solution-first rationalization.
+- **Alternatives lens** — *Are the alternatives real, or strawmen?* Take the strongest version of the rejected option — steelman it — and check whether the document engages with *that*, or with a weak caricature. An Alternatives section that dismisses each option in one dismissive sentence is a tell. Failure it catches: a foregone conclusion dressed as a comparison.
+- **Constraint lens** — *Which constraints are hard, and which are inherited habit?* Hard: physics, compliance, a one-way door already walked through, a contract with a downstream team. Soft: "we've always done it this way", a limit of the current tool, a deadline that could move. A design that treats a soft constraint as hard is under-imagined and probably larger than it needs to be. Failure it catches: unnecessary complexity justified by a fake wall.
+- **Cost lens** — *What does this design foreclose, and what does it hand the team every week for the next three years?* Name the ongoing obligation: the migration that can't be undone, the schema that now needs backfilling forever, the on-call surface. Blast radius is not just the launch; it's the maintenance tail. Failure it catches: a cheap-looking design with an expensive tail.
+- **Reversibility lens** — *One-way door or two-way door?* A two-way door (easily reverted) should be walked through, not committee'd — if the design is cheap to undo, over-reviewing it wastes everyone's time and the finding is "just ship it and learn." A one-way door (data migration, public API, external contract) deserves the scrutiny the two-way door didn't. Failure it catches: mis-spent rigor — heavy process on reversible choices, light process on irreversible ones.
+- **Failure lens** — *What has to be true for this to work, and what happens at each assumption's boundary?* List the load-bearing assumptions, then push each to its edge: what at 10x load, at zero network, at a hostile input, at the second concurrent writer? **Cross-check the prior postmortems from Step 0: does this design reintroduce a named past failure?** Failure it catches: a design sound in the happy path and broken at every boundary.
+- **Simplicity lens** — *Is there a materially smaller design that satisfies the stated goals?* Name it concretely — "drop the queue and call synchronously; the goals never mention throughput" — not "simplify it," which is not a finding. YAGNI is a soundness argument, not a style note: speculative generality is unsound because it pays cost for a goal no one stated. Failure it catches: a design solving problems it doesn't have yet.
+- **Scope lens** — *Are the non-goals temporal and justified, or is load-bearing scope being smuggled out the back?* A good non-goal says "not now, because X, and here's the seam that lets us add it later." A bad non-goal quietly excludes the hard half of the actual problem so the design looks tractable. Read every non-goal and ask whether the design still solves the real problem without it. Failure it catches: a tractable design for a shrunken problem.
+
+---
+
+## Step 3: Write findings
+
+Each finding has four parts, and a finding missing the second is an opinion — drop it:
+
+1. **Claim** — one sentence. What is unsound.
+2. **Evidence** — quote the passage or link it: `the Design section says "[quoted text]"` or `[the Migration plan](./specs/012-sync/spec.md)` assumes X. **A finding with no evidence pointer is an opinion; delete it.** This is the single discipline that separates a review the author acts on from one they resent.
+3. **Severity** — one of:
+   - **blocking** — the design should not proceed as written; a load-bearing assumption is wrong, or it reintroduces a known failure, or it solves the wrong problem.
+   - **substantive** — the design can proceed, but this materially weakens it and deserves an answer before acceptance.
+   - **minor** — worth noting, safe to defer or wave off.
+4. **Resolution** — a concrete alternative *or* the question that would settle it. "This is worse" is not actionable; "consider a two-way-door version that does X, which drops the migration" or "what happens when two agents write the same doc — does the design address that?" is.
+
+**Rank by severity, not by reading order.** Lead with the blocking findings; the author reads the top of your review and stops when they've got the gist. Burying the one blocking finding under six minor ones wastes it.
+
+---
+
+## Step 4: Calibrate — adversarially re-read your own findings
+
+Before you deliver, turn the lenses on yourself. **Reviews that flag everything teach the author to ignore reviews** — the moment your review has one indefensible finding, the author discounts all of them.
+
+- Re-read each finding as the author would and try to kill it. If you can't defend the evidence, cut it.
+- State **confidence per finding** and **what would change your mind**: "blocking, high confidence — unless the load numbers in the parent proposal are wrong, in which case this drops to minor." A finding you can't attach a falsifier to is probably a preference, not a finding.
+- Collapse duplicates. Three findings that are the same root cause are one finding with three symptoms.
+- If after calibration you have zero blocking and zero substantive findings, say so plainly — "this is sound; here are two minor notes" is a complete and valuable review. Do not manufacture severity to look thorough.
+
+---
+
+## Step 5: Deliver
+
+**In conversation by default.** Most reviews are a message: the reconstructed argument (Step 1), the ranked findings (Step 3), the calibration notes (Step 4).
+
+**Persist as a document ONLY when** the user asks, or the review is substantial enough to be cited later (a blocking review of a proposal heading to accept/reject). Then:
+
+- Write it beside the artifact it reviews: `write({ document: { path: "proposals/0003-feature-review.md" } })`.
+- Link it **from** the artifact's Unresolved questions (proposal) or Open questions (spec) section via `edit` — a plain markdown link `[design review](./0003-feature-review.md)`, never backticked, never an HTML anchor.
+- Mark it **advisory** in its own frontmatter/opening line: this is input to the author, not a verdict. The author owns the artifact and decides what lands.
+
+Never edit the design under review to "apply" a finding. You emit findings; the authoring skill applies them.
+
+---
+
+## Step 6: Hand off
+
+Route blocking and substantive findings back to whoever owns the fix:
+
+- Findings on a **proposal** → **frame-a-proposal** (the argument, alternatives, or motivation needs rework).
+- Findings on a **spec** → **write-a-spec** (goals, non-goals, migration, or test plan needs rework).
+- A finding that has *resolved into a made choice* ("we discussed it; we're going with the synchronous version") → **record-a-decision**, so the choice and its rationale land in `decisions/` with a `supersedes:` link if it overturns a prior ADR.
+- A finding that a **past failure is being reintroduced** → point the author at the specific `postmortems/YYYY-MM-DD-name.md` so the design engages with it explicitly.
+
+Name the skill and the reason in your handoff so the author knows exactly where to go.
+
+---
+
+## Non-goals
+
+- **Not a completeness checklist.** "Section X is empty" is only a finding if the emptiness makes the design unsound (no Alternatives means no evidence the option space was explored — *that's* the finding, not the empty heading).
+- **Not a fact-check.** Whether an individual claim is true is a correctness pass — a different job. You assume the claims and test whether the design that rests on them is sound. Flag a claim only when it's load-bearing AND you have specific reason to doubt it; otherwise route the fact-check separately.
+- **Not a code review.** Reviewing a diff for bugs, style, or implementation quality is out of scope. This skill reviews the design, not its code.
+- **Not a rewrite.** Never edit the artifact under review without being asked. You produce findings; the author changes the design.
+- **Never the final verdict.** The review is advice to the author, who owns the decision. A review that reads as a ruling — "rejected" — overreaches; a review that reads as "here's what would make this stronger, and here's what I'd block on and why" is doing its job.