Stats
Actions
Tags
From ok-planner
ONLY activated by explicit /discover-design slash command. Never auto-triggered by conversation content.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ok-planner:discover-designThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Two-phase autonomous pass that produces (1) a thorough as-is description
Two-phase autonomous pass that produces (1) a thorough as-is description of the project's design — the load-bearing concepts and how the code today embodies them — and (2) an explicit catalog of where the as-is design is sloppy, unspecified, unclear, overloaded, or in conflict with itself.
Runs end-to-end without user interruption. Each phase has its own
agentic produce → review → fix loop. When the skill finishes, the
human picks up via refine-design, which is the interactive session
that resolves the tensions surfaced here.
The design docs this skill bootstraps are the canonical noun catalog
for the project — what concepts exist, what they mean, where their
boundaries are, what invariants they hold. The relationship between
design and code is code references design, not the other way
around: code at points of enforcement annotates back to the design
(the way @blessed-invariant annotations already do for properties),
and the design owns the definition. A refactor that moves files around
does not invalidate the design; a code path that diverges from a
concept's stated boundary is a defect.
Capturing the as-is design plus its tensions up front is useful even
before refinement: future reviewers can distinguish a design choice
from a defect, and the tensions catalog tells them what the project
itself considers unsettled. The skill runs autonomously because the
discovery work is grunt work — read code, read prose, summarize,
classify, cross-check — and the user's design judgment is better spent
in refine-design.
Read everything the project will let you read. Code is ground truth for
what the system actually does, but prose (CLAUDE.md, READMEs,
docs/concepts/, the cold-read docs, CHANGELOG, prior specs and plans,
design sketches) is ground truth for what the project thinks the
concepts mean. Discrepancies between code and prose are tensions —
record them, do not resolve them.
.ok-planner/design/concepts/ yet._discover/ scaffolding from a prior run (the
skill picks up: phase 1 expands the existing scaffolding, phase 2
runs against the expanded set).refine-design has not yet produced human-edited concepts. Once
there are refined concepts, do not re-run discovery against the
same concepts/ directory — the skill aborts to avoid clobbering
them. Keep the design model aligned with the code through the spec
pipeline (/brainstorm → /write-plan → /execute-plan), which
changes docs and code as one unit; if a recent merge introduced
inconsistencies, run /merge to surface them..ok-planner/design/
_discover/ — phase 1 scaffolding (raw thorough descriptions)
concepts/ — phase 2 initial concept docs (one concept per file)
stories/ — phase 2 initial story docs (one story per file)
decisions/ — phase 2 initial decision docs (one decision per file)
tensions/ — phase 2 tensions / muddiness catalog
review-notes.md — agent-confessed uncertainty for the human session
_discover/ is scaffolding, not the artifact. It is wide and
detailed and may include redundancy. It is the trail of what was
observed; refine-design may eventually archive it.concepts/, stories/, decisions/, and tensions/ are the
durable outputs. They are still as-is, not prescriptive —
refine-design picks tensions with the user, writes a spec
covering the resolutions plus the code reconciliation, and then
execute-plan mutates the design files alongside the code
changes when the plan runs.review-notes.md is the agent's catalog of its own uncertainty
during this run: judgment calls it had to make, places it wasn't
sure if it identified the right concept / story / decision, areas
where the codebase was hard to read. Distinct from tensions/ —
tensions are about the codebase being muddy; review notes are
about the artifact being uncertain.The skill runs autonomously through both phases plus an optional
back-edge. No user prompts mid-run. Each phase uses an agentic loop:
producer → reviewer → (if not approved) producer-with-feedback →
reviewer → … capped at 3 review cycles per phase. If the reviewer is
still finding issues at cycle 3, the skill stops the loop, records the
unresolved issues in review-notes.md, and proceeds.
After phase 2 completes (approved or capped), the skill checks for a
phase-2 → phase-1 back-edge: if the phase 2 reviewer identified
specific areas where _discover/ was too thin to support a real
concept, the skill dispatches a focused re-discovery for just those
areas, then re-runs the extractor and reviewer for the affected
concepts only. Capped at one back-edge per skill invocation.
Run ok-planner:affirm to ensure .ok-planner/ layout exists.
Create .ok-planner/design/_discover/,
.ok-planner/design/concepts/, .ok-planner/design/stories/,
.ok-planner/design/decisions/, and
.ok-planner/design/tensions/ if absent.
Detect state:
_discover/ → phase 1 starts from scratch._discover/ → phase 1 expands existing entries and
adds new ones (idempotent).concepts/, stories/, decisions/, or
tensions/ → abort. Tell the user to either delete the
non-empty durable directories (full rerun) or, if the abort
was triggered after a recent merge, run /merge to surface
merge-introduced inconsistencies. Do not silently overwrite
human-edited artifact files.Phase 1 (Discovery):
a. Dispatch the discoverer subagent with the Phase 1 Discoverer
Prompt. It writes/expands _discover/<slug>.md files.
b. Dispatch the discovery-reviewer subagent with the Phase 1
Reviewer Prompt. It produces a structured report:
Approved | Issues Found (with specifics).
c. If Issues Found: re-dispatch the discoverer with the
reviewer's findings prepended to its prompt as
### Reviewer findings to address (cycle N). Loop back to
(b). Cap at 3 cycles total (initial + 2 fix passes).
d. If still Issues Found after cycle 3: record each unresolved
issue in review-notes.md under ## Phase 1 unresolved.
Phase 2 (Concept / story / decision extraction + tension identification):
a. Dispatch the extractor subagent with the Phase 2 Extractor
Prompt. It writes concepts/<slug>.md, stories/<slug>.md,
decisions/<slug>.md, and tensions/<slug>.md files.
b. Dispatch the extraction-reviewer subagent with the Phase 2
Reviewer Prompt. It produces a structured report and, on its
final pass (whether approved or capped), appends its
agent-confessed-uncertainty observations to review-notes.md.
The reviewer's report may include a structured
## Thin discovery requests block naming areas where phase 1
_discover/ material was too thin to support a real concept.
c. Same fix loop as phase 1, capped at 3 cycles.
d. If still Issues Found after cycle 3: record in
review-notes.md under ## Phase 2 unresolved.
Back-edge: focused re-discovery (one-shot).
## Thin discovery requests block with non-empty entries._discover/ entries (or adds new ones)
with deeper code discussion for just the listed areas.
b. Dispatch the focused-extractor subagent with the Back-Edge
Extractor Prompt. It updates the affected concepts/,
stories/, and decisions/ files in place, adds tensions
surfaced by the new material, and (only when the request
explicitly names a new artifact) adds new
concepts/<slug>.md, stories/<slug>.md, or
decisions/<slug>.md files.
c. Dispatch the phase 2 reviewer one more time (using the same
Phase 2 Reviewer Prompt) with scope restricted to the
artifacts affected by the back-edge. The reviewer appends a
## Phase 2 review notes (back-edge) section to
review-notes.md covering any residual uncertainty about
the back-edge work.review-notes.md under ## Back-edge residual thinness for
the human — do not loop.Regenerate the design catalog summaries. For each of
concepts/, stories/, and decisions/, read every file
(skipping _merged/ subdirectories if present) and produce a
one-shot-readable TOC alongside it:
concepts/ → concepts.md (entries: slug, optional aliases,
first sentence of ## What it is)stories/ → stories.md (entries: slug, one-line summary
drawn from the story's As ... I can ... statement)decisions/ → decisions.md (entries: slug, one-line summary
drawn from the decision's Choice: line)These TOCs are the one-shot-readable catalogs consulted by skills that read the design docs (brainstorm, refine-design, merge, review-holistic); they let agents know what artifacts exist without reading every full file. Generated; agents should not edit them by hand.
Format (use the same shape for all three):
# <Concept|Story|Decision> catalog (auto-generated)
Read first. Then either grep for the matching annotation
(`@concept:` / `@story:` / `@decision:`) in the code under
review, or read `<dir>/<slug>.md` for the full body. Generated
by `discover-design` and refreshed by `execute-plan` when a
plan touches the catalog. Do not edit by hand — changes will
be overwritten.
## <Concepts|Stories|Decisions>
- `<slug>` — <one-sentence summary, ≤120 chars>
- `<slug>` (aliases: <comma-list>) — <one-sentence summary>
Sort entries alphabetically by slug. Omit the (aliases: ...)
parenthetical when there are no aliases. Aliases apply mainly
to concepts; stories and decisions typically have none.
Final report to the user: number of _discover/ entries,
number of concepts, number of stories, number of decisions,
number of tensions grouped by category, count of review-notes
entries, whether a back-edge ran, and the next-step pointer
(run /refine-design).
The skill does not prompt the user mid-run. The final report is the only thing the user sees during this skill's execution.
Some embedded prompts below carry {{SELF-CONTAINMENT-RULE}} and
{{TENSION-SURFACE-RULE}} placeholders. When you assemble a subagent
prompt for dispatch, replace each placeholder with the body of the
matching ### block in this section (the prose under the header, not
the header line) — the same substitution you already do for the
bracketed [plan path]-style values. The convention: {{...}} flags a
static block to inline; [...] flags a per-run value to fill.
These two rules govern what may appear in concept bodies and tension resolution sections. Three separately-dispatched subagents need them — the extractor (which authors the docs), the extraction reviewer (which audits them), and the back-edge extractor (which mutates them). Each is its own dispatch and sees only its own prompt, so defining the rules once here and transcluding them keeps the wording from drifting between the agent that writes and the agent that checks.
Concept, story, and decision bodies are self-contained. The design
owns the definition; code references it via @concept:, @story:,
and @decision: annotations. A refactor that moves files around
does not invalidate an artifact, and an external doc that moves to
another repo does not orphan one. Citations in artifact body are
restricted to forms that survive the codebase moving.
The rule applies to frontmatter as well as body. A references:
frontmatter field that lists _discover/... artifacts, spec paths,
sketch paths, or any other file-form citation is the same durability
problem the rule exists to prevent — those paths rot when the
scaffolding is retired, when specs are archived, or when the repo is
reorganized. Once an artifact is baked, the lineage that produced it
lives in the _discover/ scaffolding (as history) and in the git
history of the artifact file itself; the artifact body and frontmatter
carry no lineage. Frontmatter is restricted to slug-form metadata
only: concept: / story: / decision: / tension:, status:,
aliases: (list of names), and for tensions category: and
affects: (list of slugs). Path-form references: does not belong
in any artifact's frontmatter; if a discover-design or
earlier-version run wrote one, strip it.
Allowed in artifact body (concepts / stories / decisions):
see also: claim-handle,
concept:claim-handle, story:claim-co-holder,
decision:persistence.@blessed-invariant: 4,
@agent-contract: X) — the ID is stable across file moves; the
file path is not.Disallowed in artifact body (concepts / stories / decisions):
foo/bar.go, pkg:foo/bar/baz,
services/widget/, etc.) — bare or in any citation form, in-tree or
in a sibling repo.code:foo.go::Symbol, pkg:github.com/..., bare
URLs, "the code at X" pointers.docs/..., READMEs, CHANGELOG,
sibling-repo paths).If an artifact feels like it can't say what it needs to without naming
a file, that's either (a) a hint that the artifact's boundary is
muddier than the current text claims — file a tension — or (b)
material that belongs in the _discover/ scaffolding (Code surface
section), not in the artifact body.
The ## Evidence section is a snapshot — it documents the specific code
or prose that motivated the tension, and may rot when the cited surface
moves. That's expected; tensions are point-in-time observations of
muddiness. Code-citation evidence is fine in ## What is muddy and
## Evidence.
The ## Resolution candidates section is different: resolutions become
spec instructions, and the spec lives forward in time. State resolution
shapes as durable concept mutations (which concept's Definition /
Boundaries / Invariants change, and how) and as durable code-discipline
changes (what property the code will hold). Resolution shapes must NOT
cite specific files, paths, or symbols — those will rot before the
tension gets resolved.
Agent (general-purpose):
## Discover-Design Phase 1: As-Is Discovery
### Goal
Read the codebase and the project's prose, and produce thorough
as-is descriptions of every load-bearing piece of structure. Output
goes to `.ok-planner/design/_discover/` as one file per topic.
This is scaffolding, not the final artifact. Be wide and detailed.
Redundancy is fine — phase 2 will merge.
### What you can read
Everything. Source, tests, schemas, migrations, protos, build files,
inline annotations, CLAUDE.md, READMEs, `docs/`, `cold-read/`,
CHANGELOG, prior specs under `.ok-planner/specs/`, prior plans
under `.ok-planner/plans/`, design sketches under
`.ok-planner/sketches/`, archived material under
`.ok-planner/archive/` if present.
Code is ground truth for what the system does. Prose is ground
truth for what the project thinks the concepts mean. Capture both.
When code and prose disagree, capture both versions — don't
resolve. (Phase 2 will catalog the disagreement as a tension.)
### Existing scaffolding
If `.ok-planner/design/_discover/` already contains files, those
are from earlier runs (possibly from an earlier, narrower version
of this skill that only read code). For each existing entry:
- Re-read the source it cites.
- Expand it with deeper code discussion (more file:line citations,
more about how the structure interacts with neighbors, more
explicit statement of invariants and boundaries).
- Pull in prose sources that corroborate or contradict its claims.
- Update the file format to match the per-entry template below
(`Description / Code surface / Prose surface / Adjacent topics /
Observations`). The legacy ADR template (Decision / Rationale /
Consequences) is no longer used; replace it.
- Do NOT delete or rename existing entries unless they describe
something that turned out not to exist in the code.
If the project clearly has structure that the existing `_discover/`
set didn't cover, add new entries for it.
### Reviewer findings to address (cycle N)
(This block is empty on the first run. On fix-loop cycles, it
contains the reviewer's findings; address each one before
reporting back. Do not consider yourself done while any reviewer
finding remains unaddressed.)
### What to discover
Each entry should describe one piece of load-bearing structure. The
bar for "load-bearing" is: a reasonable engineer working on this
codebase needs to know this exists and what it does. Concretely:
- Concepts (nouns) the system traffics in: claim, frame, instance,
template, node, executor, etc. For each, capture: definition,
what it does, where it lives in code, what its boundaries are,
what neighboring concepts it interacts with.
- Invariants the code maintains, including annotated ones
(`@blessed-invariant`, `@agent-contract`, etc.) and unannotated
ones the code clearly enforces.
- Cross-cutting disciplines: opacity rules, transaction shapes,
error-handling patterns, naming conventions, layering rules
enforced by lint configs.
- Schema-level commitments visible in migrations: table layout,
FK semantics, indexes, advisory locks.
- Module / package boundaries and the rules that govern them.
- Choices that are choices (one shape over an alternative), where
the alternative is identifiable.
- Negative choices: things the project deliberately does NOT do.
- Aliases, deprecated names, transitional shims (these often
become tensions in phase 2).
### Per-entry template
Write each entry to `.ok-planner/design/_discover/<slug>.md`
(kebab-case, no date prefix — these are scaffolding, not dated
decisions). Template:
```markdown
---
topic: <slug>
kind: concept | invariant | discipline | schema | boundary | choice | alias
---
# <Topic title>
## Description
<Several paragraphs of as-is description. What it is, what it
does, why the project has it, where it lives in code, how it
interacts with neighbors. Be thorough — this is the raw material
phase 2 will work from. Multiple paragraphs is the norm, not the
exception.>
## Code surface
<Specific files / packages / line ranges where this thing is
enforced or expressed. List liberally.>
## Prose surface
<Where prose talks about this — CLAUDE.md sections, doc paths,
spec references. If code and prose disagree, note both with
specific citations.>
## Adjacent topics
<Other `_discover/` entries this one touches. Cross-reference
liberally; phase 2 uses these to identify boundary tensions.>
## Observations
<Anything you noticed that didn't fit into Description but
matters: aliases in use, vestigial bits, inconsistent
spellings, places where the concept appears to be doing double
duty, places where two parts of the code disagree about what
this thing is, places where prose and code drift apart. These
are tension candidates for phase 2 — do not classify them here,
just record.>
cmd/*, main.*, bin/*).@blessed-invariant,
@agent-contract, @source, @diverged, @concept).docs/concepts/ material, any cold-read/
material.When done, output a structured report:
## Phase 1 — Discovery Reviewer Subagent Prompt
Agent (general-purpose):
Review the as-is discovery scaffolding under
.ok-planner/design/_discover/ for completeness, depth, and
correctness. Produce a structured report: Approved or Issues Found with specifics. The producer will revise based on your
findings; be specific enough that they can act.
@blessed-invariant,
@agent-contract) has a corresponding _discover/ entry, or is
folded into one. Every top-level interface in shared
infrastructure packages has coverage. Every migration's
structural intent is captured somewhere._discover/ slugs, not invented ones..ok-planner/design/_discover/.git grep -l @blessed-invariant
and git grep -l @agent-contract (or the project's equivalent)
— every annotation should map to an entry.Status: Approved | Issues Found
## Findings
(if Issues Found, one entry per issue:)
### <file>: <one-line summary>
<Specific actionable description. What is wrong. What needs to
change. Where the missing content should live.>
(if Approved:)
(empty Findings section)
## Coverage summary
- <bucket>: <count> entries
- <bucket>: <count> entries
- <areas with no coverage that the reviewer believes do not need
coverage>: <list>
## Phase 2 — Extractor Subagent Prompt
Agent (general-purpose):
Read the _discover/ corpus and produce:
.ok-planner/design/concepts/..ok-planner/design/stories/..ok-planner/design/decisions/..ok-planner/design/tensions/.This is still as-is. Stories describe what the product does
today; decisions describe what choices have been made. Do NOT
propose resolutions to tensions, do NOT invent stories the
product does not yet deliver, and do NOT propose decisions the
project has not yet made. Document the as-is;
refine-design and future brainstorm/execute-plan runs
evolve the model.
.ok-planner/design/_discover/. This is your
primary source.(This block is empty on the first run. On fix-loop cycles, it contains the reviewer's findings; address each one before reporting back.)
A noun the system traffics in. The bar is: a reviewer reading code that mentions this noun needs a stable definition to know what it means. Examples (concretely project-dependent):
One concept per file. Merge multiple _discover/ entries when
they describe the same noun.
Write each concept to .ok-planner/design/concepts/<slug>.md.
Slug is the preferred name; aliases go inside the file.
---
concept: <slug>
status: as-is
aliases:
- <other names this concept goes by in code/prose>
---
# <Concept name>
## What it is
<Definition. One paragraph. Should stand alone — a reader who
has never opened the repo should be able to identify what this
is.>
## Purpose
<Why this concept exists. What it makes possible that a flatter
design without this concept could not. What problem its
presence solves.>
## Boundaries
<What is in this concept, what is NOT (and lives in a neighbor
concept), and which adjacent concepts it interacts with. Name
the neighbors with their slugs (`see also: <slug>`).>
## Invariants
<Load-bearing properties stated as properties of the concept,
not as descriptions of code. Annotated invariants
(`@blessed-invariant`, `@agent-contract`) belong here — list
them with their IDs if the codebase numbers them.>
## Aliases
<Other names this concept currently goes by in code or prose
today. List only names that actually appear in the live
codebase or live prose — not retired names, not names
someone used to use. If multiple live names point at the
same concept, that is itself a tension candidate — produce a
corresponding tensions/ entry. Drop this section entirely if
there are no live aliases.>
{{SELF-CONTAINMENT-RULE}}
A user-outcome the running product already delivers — a capability a user can observe by driving the assembled product. The bar is: a reasonable user (or a third party watching one) can see this happen, not by reading code but by using the product. Examples (concretely project-dependent):
The delivery surface is not part of the story. Which
surface a user reaches through — CLI verb, HTTP route, wire
message, scheduled job, UI — is a technical choice and lives
in decisions/, not in the story. The story names the
capability and what the user observes; the decision names how
the product exposes it. Two stories that describe the same
user-outcome through different surfaces are one story (the
surface is the decision's territory).
Discover stories from:
decisions/, the user-outcome it serves into stories/.).ok-planner/history/specs/ if present —
every shipped spec carried stories that now describe what
the product does.Write each story to .ok-planner/design/stories/<slug>.md.
---
story: <slug>
status: as-is
---
# <Short story title>
## Story
As <role>, I can <capability>, so that <business value>.
## Acceptance
<What the user does, in their terms> → <what they observe
happening>. The component that delivers the value is real (not
stubbed) — name it. The surface the user reaches through is a
technical decision (captured in `decisions/`), not part of the
story.
## Falsifier
<The user-observable absence that would prove this story is NOT
delivered: the user takes the action and the promised result
never appears; the result appears but is unrelated to their
input; the result looks real but the underlying state is
synthetic (a stubbed or canned value-delivering component).>
## Proof
<Demo | example | proof | all-of-the-above> — <what the proof
must exhibit to a third party so they would conclude the story
is delivered>.
A technical choice the project has clearly made: one shape adopted over an identifiable alternative. The bar is: a reasonable engineer can identify both the choice and a plausible different choice the project could have made. Examples (concretely project-dependent):
pgx driver (alternatives:
SQLite, a different driver)"One decision per choice. Don't lump unrelated choices into one file.
Discover decisions from:
_discover/ Observations sections flag as
"choice with an identifiable alternative."Write each decision to
.ok-planner/design/decisions/<slug>.md.
---
decision: <slug>
status: as-is
---
# <Short decision title>
## Choice
<The option the project adopted. One or two sentences, concrete
and unambiguous.>
## Rationale
<Why this choice over the alternatives. Source from code,
comments, ADRs, or the most plausible reading of the code's
shape. If the rationale is genuinely unclear, file a tension
rather than fabricating one.>
## Alternatives
<The options the project could have taken instead. One bullet
each. Brief — these are not full proposals, just enough to
show what was on the table.>
Anything about the as-is design that is sloppy, unspecified, unclear, overloaded, conflicting, or vestigial. Categories (use these in frontmatter):
overloaded — one name means multiple things.unspecified — something load-bearing has no name, or its
boundary is undefined.unclear — concept exists, but its definition is fuzzy or
different parts of the project disagree.inconsistent — same property implemented two ways, or same
concept spelled two ways, or same constraint with different
cutoffs.conflicting — two parts of the code or two prose sources
actively contradict each other.vestigial — concept named or annotated but no longer
load-bearing.muddy-boundary — adjacent concepts blur into each other.Write each tension to .ok-planner/design/tensions/<slug>.md.
---
tension: <slug>
category: overloaded | unspecified | unclear | inconsistent | conflicting | vestigial | muddy-boundary
status: open
affects:
- <concept-slug>
- <concept-slug>
---
# <Short tension title>
## What is muddy
<Describe the tension. Be specific. Quote code or prose where
helpful (with file:line). State exactly which two things
disagree, or what is missing, or what is overloaded.>
## Why it matters
<What downstream consequence falls out of this tension.>
## Resolution candidates (do NOT pick)
<List the resolution shapes the tension admits, without picking
one. If you don't see a clean shape, say so. refine-design
walks this with the user.>
## Evidence
<Specific citations: code paths, prose paths, _discover/
entries.>
{{TENSION-SURFACE-RULE}}
Concept, story, decision, and tension bodies describe the project as it stands today. They are not journals and they are not roadmaps. Two failure modes to avoid:
## Notes / ## History /
## Changelog section on any concept, story, decision,
or tension file. If you find one (in a hand-written
artifact or an older-version output), strip it.tensions/, where they are tracked as
explicitly unresolved; intended future changes go in a
spec, not the design doc. Nothing in the durable model is
aspirational.The exception is the discovery scaffolding kept around as
judgment-call surface: _discover/ (phase-1 raw notes) and
review-notes.md (agent-confessed uncertainty consumed by
/refine-design). Those are explicitly point-in-time
artifacts; the durable model is not.
When a spec changes a concept / story / decision, the spec rewrites the affected section in place to reflect the new state. The git commit carries the lineage. Do not paste a dated entry into the artifact body.
_discover/, the concept / story / decision file alone is
enough.@concept: / @story: / @decision:
annotations. See the "Self-containment rule" above.## Resolution candidates section. See the "Tension
surface rule" above.## Notes, ## History, ## Changelog, or
any dated-audit-trail section to a concept, story,
decision, or tension. See the "Current-state-only rule"
above.tensions/.When done, output:
_discover/ entries that produced no artifact (folded into
another, or noise — say which).
## Phase 2 — Extraction Reviewer Subagent Prompt
Agent (general-purpose):
Review the concept, story, decision, and tension catalogs
produced by the extractor. Produce a structured report
(Approved or Issues Found) AND, on your final pass (whether
approved or capped), append your observations about the
artifact's residual uncertainty to
.ok-planner/design/review-notes.md. The review-notes file is
the agent-confessed-uncertainty surface the human reviews in
refine-design.
concepts/<slug>.md. If two files describe the same thing,
flag as an issue (extractor must merge)._discover/.see also: neighbors or explains why it has none._discover/ that
actually appears in current code or prose is either listed
here or has its own concept (if it actually refers to
something else). Aliases that no longer appear anywhere live
must not be listed — see the "Current-state-only rule"
above.tensions/<slug>.md, not in a forward-looking
section of the concept body. If the extractor wrote an
"Open within this concept" or similar section into a concept
file, flag it.## Notes /
## History / ## Changelog section, no dated audit-trail
entries, no "previously called X" / "used to be Y" /
"changed per spec Z" lines, no forward-looking "TODO" /
"deferred" / "will be replaced" content. Lineage lives in
git; open items live in tensions/. See the
"Current-state-only rule" above.decisions/, not story content).## Notes /
## History / ## Changelog section, no dated audit-trail
entries, no backward- or forward-looking phrasing. See the
"Current-state-only rule" above.## Notes /
## History / ## Changelog section, no dated audit-trail
entries, no backward- or forward-looking phrasing. See the
"Current-state-only rule" above. (Alternatives is the list
of options the project could have taken — that's not
forward-looking; it's the as-is shape of the choice. But
"we may switch to alternative X" or "the chosen option was
formerly Y" violates the rule.)overloaded tension actually describes one name
meaning multiple things; an inconsistent tension actually
describes one thing implemented two ways; etc._discover/ entries — not "somewhere in the codebase".Resolution candidates lists actual shapes, not generic
advice: "Pick A or B" with concrete A and B descriptions,
not "decide what to do".Resolution candidates is path-free: hold the resolution
shapes to the tension surface rule reproduced under "Rules
being enforced" below. State the change at the concept level
(which concept's Definition / Boundaries / Invariants would
change). Code-citation evidence is fine in ## What is muddy
and ## Evidence; the resolution shapes must be path-free.The two self-containment checks above hold against these. This reviewer runs as its own dispatch and does not see the extractor prompt, so the rules are reproduced here in full.
{{SELF-CONTAINMENT-RULE}}
{{TENSION-SURFACE-RULE}}
concept.aliases alias actually appears in current
code or prose. Aliases are a list of live names — not
retired names, not historical names. If an alias does not
appear anywhere live, drop it from the list. If multiple
live names point at the same concept and the project
should converge, that is a tension — produce a
corresponding tensions/ entry rather than recording the
convergence intent in the concept body._discover/ lands somewhere
in either concepts/ (as an invariant) or tensions/ (as
vestigial / inconsistent)._discover/ entries are reflected: each entry should be
either folded into a concept or noted as deliberately not
promoted (in the extractor's report — verify the report
accounts for them all).On your final review (whether you approved or the loop was
capped), append a section to
.ok-planner/design/review-notes.md (create the file if absent)
capturing the artifact's residual uncertainty. Distinct from
tensions — these are about the artifact itself, not the
codebase:
_discover/ was thin and the human may want
to ask the discoverer for another pass.Append using this format:
## Phase 2 review notes (cycle <N>)
### Judgment calls
- <concept-slug>: <what was decided and what the alternative was>
- …
### Suspected-but-unconfirmed concepts
- <noun>: <why might be load-bearing, why not confident>
- …
### Possible merges / splits to reconsider
- <slug>: <observation>
- …
### Thin discovery areas
- <topic>: <what was missing>
- …
### Unresolved issues (when applicable)
- <issue>: <what could not be fixed in the loop>
- …
Sections with no entries can be omitted.
Distinct from the prose Thin discovery areas section in
review-notes. Use a structured block at the bottom of your
report when you can identify specific code areas the discoverer
missed and that, if expanded, would let the extractor produce a
meaningfully sharper concept. The skill consumes this block to
drive the one-shot back-edge (focused re-discovery + re-extraction
Include only items that meet ALL of these:
Do NOT use this block for issues that the fix loop already addressed, for issues that are really tensions, or for general "could be deeper" wishes.
Format:
## Thin discovery requests
### <affected-concept-slug>
- Scope: <code paths to re-read, e.g. `modeling/qualityrule/eval/`>
- Missing: <one sentence stating what the concept can't currently say>
- Promote new concept: <name | none>
Omit the block entirely if no requests apply.
Status: Approved | Issues Found
## Findings
(if Issues Found:)
### <file>: <one-line summary>
<Specific actionable description.>
(if Approved:)
(empty Findings section)
## Catalog summary
- Concepts: <count>
- Tensions by category:
- overloaded: <count>
- unspecified: <count>
- …
- Review notes appended: <count> in <sections>
- Thin discovery requests: <count>
## Thin discovery requests
(Structured block per the spec above. Omit if empty.)
## Back-Edge — Focused Discoverer Subagent Prompt
Agent (general-purpose):
Phase 2 review identified specific areas where _discover/
material is too thin to support a real concept. Your job is to
expand the _discover/ entries for ONLY the listed areas. Read
the named code paths, then update the named entries with deeper
discussion. If a request explicitly authorizes promoting a new
_discover/ entry, add it.
This is scoped re-discovery — NOT a full re-pass. Do not touch
other _discover/ entries. Do not survey the codebase broadly.
(Filled in by the skill orchestrator from the phase 2 reviewer's
## Thin discovery requests block. Each entry names:
Only the code paths named in the thin discovery requests. You may follow imports / call sites within those paths. Do not read prose surfaces unless they directly explain the named code area.
For each request:
_discover/<slug>.md entry that backs the
affected concept. There may be more than one. If there is none,
that's a signal to either (a) add a new entry under a slug the
request implies, or (b) report back that no entry exists and
one needs to be created.Do NOT change the entry's topic or kind frontmatter.
Do NOT touch entries that are not named in any request.
Same as the phase 1 template (Description / Code surface / Prose surface / Adjacent topics / Observations). Your edits keep that shape.
/discover-design run.Output a short structured report:
_discover/ entry was expanded (or
created); a one-line summary of the new material.Keep under 400 words.
## Back-Edge — Focused Extractor Subagent Prompt
Agent (general-purpose):
The focused discoverer just expanded specific _discover/
entries. Update the affected concepts/, stories/, and
decisions/ files to reflect the new material, and add
tensions surfaced by the expansion. Add new artifact files
(concepts/<slug>.md, stories/<slug>.md,
decisions/<slug>.md) ONLY when the original thin discovery
request explicitly authorized "Promote new artifact".
(Filled in by the orchestrator. Each request names the affected artifact kind (concept / story / decision), its slug, the discoverer's expansion summary, and whether a new artifact may be promoted.)
concepts/<slug>.md,
stories/<slug>.md, or decisions/<slug>.md) and the
now-expanded _discover/<slug>.md entry/entries.What it is, Purpose, Boundaries,
and Invariants to reflect what the request flagged as
missing.Story, Acceptance, Falsifier, or
Proof to reflect what the deeper read revealed about the
observable outcome.Choice, Rationale, or
Alternatives to reflect what the deeper read revealed
about the choice's shape or motivation.see also: / Adjacent references.tensions/<slug>.md per the standard tension template.Do NOT touch artifact files or tension files unrelated to the affected slugs. Do NOT add new artifacts that weren't authorized.
Concept bodies you edit or create, and any tension you add, must follow these. This step runs as its own dispatch, so the rules are reproduced here in full.
{{SELF-CONTAINMENT-RULE}}
{{TENSION-SURFACE-RULE}}
Output a short structured report:
Keep under 300 words.
## The `@concept:`, `@story:`, `@decision:` annotation convention
The design docs are the canonical source for what each artifact
means. Code references the design via in-source annotations:
- `@concept: <slug>` — load-bearing site where a concept is
enforced or expressed
- `@story: <slug>` — load-bearing site for delivering a story's
user-observable outcome (the wired entry point, the handler that
produces the observable effect, the value-delivering component)
- `@decision: <slug>` — site that embodies a technical decision
(the persistence call, the registration mechanism, the chosen
cadence)
These mirror the project's existing `@blessed-invariant`,
`@source:`, `@diverged:`, `@agent-contract` patterns. Each annotation
marks a load-bearing site, not every file that happens to touch the
artifact.
Two artifacts together replace the need for an external index:
- **`.ok-planner/design/concepts.md`** (and `stories.md`,
`decisions.md`) — auto-generated summaries (this skill produces
them). Agents read them in one shot at the top of any skill that
reads the design docs to know what artifacts exist.
- **Annotations in source** — discoverable by
`rg '@(concept|story|decision): <slug>'`. Answers both "which
artifacts apply to this file?" (read the file) and "where is
artifact X load-bearing?" (grep across the repo).
Annotation rollout is incremental: any time an agent consults an
artifact to understand or modify a file, it leaves the annotation
at the most-specific load-bearing site so the next agent doesn't
have to re-do the lookup. This rule is documented in
`.ok-planner/CLAUDE.md` (written by `ok-planner:affirm`) so it
applies project-wide regardless of which skill is active. No bulk
greenfield annotation pass is needed.
## Re-run discipline
The skill is idempotent on `_discover/`: re-running deepens existing
entries and adds new ones.
The skill refuses to re-run when `concepts/`, `stories/`,
`decisions/`, or `tensions/` are non-empty, because they may contain
human edits from `refine-design`. To force a full rebuild, the user
must delete the non-empty durable directories first (preserving
`_discover/` if they want phase 1 to be incremental). After
refinement, the design model stays aligned with the code through the
spec pipeline (`/brainstorm` → `/write-plan` → `/execute-plan`),
which changes docs and code as one unit; `/merge` surfaces
merge-only inconsistencies that the pipeline can't prevent.
## What this skill does NOT do
- Doesn't prompt the user mid-run. The only user-visible output during
execution is the final summary.
- Doesn't propose resolutions to tensions. That's `refine-design`'s
job.
- Doesn't write the prescriptive "as it should be" design. The outputs
are as-is. The prescriptive version emerges when `refine-design`
packages chosen tensions into a spec and `execute-plan` applies the
resulting concept-file mutations.
- Doesn't grade implementations or call out defects in the code. The
design describes what the project is and where it's muddy. Defects
are found by the review skills.
- Doesn't introduce code annotations (`@concept:` etc.). That's a
separate convention introduced after the prescriptive design is
stable.
- Doesn't overwrite human-edited `concepts/` or `tensions/`. Aborts
rather than risk data loss.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub fallguyconsulting/ok-planner --plugin ok-planner