rsc-universal 0.1.1

package/skills/specify/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: specify
+description: "Use when a feature, change, or product idea is still fuzzy and needs to become a written spec BEFORE any planning or code — turn a one-line intent into a WHAT/WHY specification (problem, goals, users, scope, behaviour, acceptance criteria) with zero implementation detail. Triggers: 'write a spec for…', 'spec this out', 'especifica esta feature', 'I want to add X but haven't thought it through', 'capture requirements for…', 'what should this feature do', 'draft a PRD', 'define the feature before we build', kicking off an SDD feature after the constitution exists, or any moment someone jumps to HOW before WHAT is agreed. Asks ONE focused question at a time only where it cannot infer, then writes 02-DOCS/wiki/sdd/specs/<slug>.md and marks open points to clarify. NOT the technical plan (that's `plan`), NOT the de-risking ambiguity sweep (that's `clarify`), NOT project-wide principles (that's `constitution`)."
+tags: [sdd, spec, requirements]
+recommends: [clarify, plan]
+profiles: [core, full]
+origin: risco
+---
+
+# Specify — intent becomes a spec
+
+This is the **specify** phase of the rsc-sdd chain: `constitution` → **`specify`** → `clarify` → `plan` → `tasks` → `analyze` → `implement` → `verify` → `review` → `ship`. Its single job is to turn a fuzzy intent into a written specification that states **WHAT** the change is and **WHY** it matters — and nothing about **HOW** it gets built.
+
+A spec is a contract about behaviour and outcomes, readable by a non-technical stakeholder and precise enough that a `plan` can be derived from it. The output is one file: `02-DOCS/wiki/sdd/specs/<slug>.md`, indexed in the root `CLAUDE.md` Knowledge map.
+
+## The one rule that defines this skill
+
+**No implementation leaks.** The moment the spec names a framework, a table schema, a library, an endpoint shape, a file path, or an algorithm, it has stopped being a spec. Those decisions belong to `plan` and the stack skills. Specify describes the *observable behaviour and the reason for it*; the system that delivers it is deliberately left open.
+
+If you cannot describe a requirement without naming the technology, you have found a real question — record it as a point to clarify, do not guess the answer.
+
+## Read the room first (accompaniment dial)
+
+Before asking anything, read `02-DOCS/wiki/harness/user-profile.md` for the technical level and accompaniment level, and adapt:
+
+- **L0 "cavernícola"** — infer aggressively from the intent and any existing wiki/constitution. Ask only the questions whose answer would change the spec's scope. Draft, show, move on.
+- **L1 "breve"** — one line of *why* per question; ask the few that genuinely matter.
+- **L2 "explica decisiones"** — justify each requirement as you record it; surface the trade-offs you inferred.
+- **L3 "acompañamiento total"** — explain what a spec is and is not, walk every section, ask freely (still one question at a time), confirm each answer before recording it. Ideal for non-technical users.
+
+If no profile exists, default to non-technical framing and keep questions plain. Never assume fluency.
+
+## Questioning discipline — one at a time, only where you can't infer
+
+The failure mode of specs is the wall of twenty questions. Avoid it:
+
+1. **Infer first.** Read the `constitution` (`02-DOCS/wiki/sdd/constitution.md`), the existing wiki, and sibling specs. Fill every section you reasonably can from what already exists.
+2. **Ask only the gaps that change the spec.** A question earns its place only if a different answer would change scope, a goal, a user, or an acceptance criterion. Cosmetic gaps become *points to clarify*, not questions.
+3. **One focused question per turn.** Ask, wait, record, then ask the next. Never batch. Phrase in the user's technical register.
+4. **When inference and asking both fail, mark it.** Anything you cannot resolve in this pass becomes an explicit entry in *Points to clarify* — that list is the handoff contract to the `clarify` phase, not a defect.
+
+Stop asking when the WHAT and WHY are complete enough to plan against. Remaining unknowns live in *Points to clarify*; you do not need every answer before writing the file.
+
+## What a good spec contains
+
+Write these sections into `02-DOCS/wiki/sdd/specs/<slug>.md` using `references/spec-template.md`. Keep every line about behaviour and intent.
+
+| Section | Holds | Watch for |
+| --- | --- | --- |
+| Problem & why | The pain, the cost of not solving it, the trigger | A "solution" disguised as a problem |
+| Goals | What success delivers, in outcome terms | A "goal" that's actually a HOW |
+| Non-goals / out of scope | What is explicitly NOT done now — adjacent work, deferred features | Silence — unsaid scope becomes assumed scope |
+| Users & context | Who acts, their context, what they're trying to achieve | An imagined user no one asked for |
+| Behaviour | What the system does, in observable terms, incl. main + edge + error paths | A verb that's actually a HOW ("queries", "caches") |
+| Acceptance criteria | Testable, binary checks that say "done" | Vague critera ("works well", "is fast") |
+| Points to clarify | Open questions, assumptions made, decisions deferred | Pretending there are none |
+
+### Acceptance criteria carry the weight
+
+Each criterion is a binary, observable statement — true or false, no judgement call — phrased so `verify` can later check it and `tasks` can derive a done-check from it. Prefer the **Given / When / Then** shape; it forces a concrete trigger and a concrete outcome.
+
+```text
+Given a signed-in user with an empty cart
+When they open the checkout page
+Then they see an empty-cart message and the "pay" button is disabled
+```
+
+A criterion that needs a human to "decide if it's good enough" is not done yet — sharpen it or move the soft part to *Points to clarify*.
+
+## The pass, end to end
+
+```text
+1. READ profile + sdd config + constitution + existing specs → set verbosity, inherit principles, avoid dupes
+2. IF risky/architectural, DRAFT proposal first              → alternatives, tradeoffs, risks, rollback
+3. RESTATE the intent in one sentence                        → confirm you understood before drafting
+4. INFER every section you can                               → from constitution, wiki, the intent itself
+5. ASK the gaps that change scope, one at a time             → record each answer, then ask the next
+6. DRAFT 02-DOCS/wiki/sdd/specs/<slug>.md                     → WHAT/WHY only, template sections filled
+7. LIST Points to clarify                                    → open questions + assumptions, the clarify handoff
+8. INDEX it in root CLAUDE.md Knowledge map                   → under the sdd/specs topic
+9. END with result envelope and HAND OFF to clarify           → name the next phase explicitly
+```
+
+`<slug>` is a short kebab-case name derived from the feature (e.g. `bulk-csv-import`, `magic-link-login`). If a spec with that slug exists, read it and update rather than overwrite.
+
+## Worked shape (abridged)
+
+```markdown
+# Spec — Magic-link login
+
+## Problem & why
+Password resets are the #1 support ticket and a sign-up drop-off point.
+A passwordless email link removes the password entirely.
+
+## Goals
+- A user can sign in with only their email, via a one-time link.
+- No password is ever stored or required.
+
+## Non-goals / out of scope
+- Social login (Google/Apple) — deferred.
+- Replacing existing sessions for already-signed-in users.
+
+## Users & context
+A returning user on a new device who does not remember a password.
+
+## Behaviour
+- Main: user enters email → receives a link → following it signs them in.
+- Edge: an expired link shows a "request a new link" path.
+- Error: an unknown email reveals nothing (same response as a known one).
+
+## Acceptance criteria
+- Given a registered email, When the user requests a link and follows it within
+  its validity window, Then they are signed in.
+- Given an expired link, When it is followed, Then sign-in is refused and a new
+  link can be requested.
+
+## Points to clarify
+- Link validity window? (assumed: short, exact value deferred to clarify)
+- Rate-limit on requests per email? (deferred)
+```
+
+Note what is *absent*: no token format, no table, no email provider, no framework. Those are `plan`'s job.
+
+## Optional proposal / pre-execution briefing
+
+For a tiny feature, skip this. For ambiguous, architectural, high-risk, high-review-cost or research-heavy work, write a proposal before the spec:
+
+```text
+02-DOCS/wiki/sdd/proposals/<slug>.md
+```
+
+Proposal grammar:
+
+```markdown
+# Proposal — <slug>
+
+## Problem
+## Intent
+## Scope / Non-scope
+## Research input
+## Alternatives considered
+## Tradeoffs
+## Risks
+## Rollback
+## Success criteria
+## Recommendation
+```
+
+The proposal is allowed to mention options and tradeoffs; the spec that follows still stays WHAT/WHY. If research came from a transcript, doc, spike, or external briefing, cite it in `Research input` so the decision trail survives the chat.
+
+## Anti-patterns → STOP
+
+| If you're about to… | Reality / Fix |
+| --- | --- |
+| Name a framework, table, endpoint, or library | That's HOW. Strip it; describe the behaviour instead, or log the open question. |
+| Dump 12 questions in one message | One focused question per turn. Infer the rest from the constitution and wiki. |
+| Ask a question you could answer from the constitution | Read it first. Only ask what genuinely changes the spec. |
+| Write "it should work well / be fast / be intuitive" | Not testable. Make it a binary Given/When/Then or move it to Points to clarify. |
+| Skip non-goals because "it's obvious" | Unsaid scope becomes assumed scope. State what you are *not* doing. |
+| Resolve every ambiguity yourself to look finished | Inventing answers is worse than naming gaps. List them in Points to clarify. |
+| Start designing the solution because it's clearer | Stay on WHAT/WHY. The plan is a later, separate phase. |
+| Write the spec somewhere other than 02-DOCS/wiki/sdd/specs/ | That's the canonical location the rest of the chain reads. Use it. |
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+- Read `02-DOCS/wiki/sdd/config.yaml` if present. If it is missing and the change is non-trivial, recommend `sdd-init` before proceeding; if the user asks to continue, record the missing config as a risk.
+- Read `02-DOCS/wiki/sdd/constitution.md` first — its principles are inherited constraints, not things to re-decide. If it's missing, note that the project has no constitution yet and suggest the `constitution` phase before continuing (you can still draft a spec, but flag the absence).
+- **No constitution yet?** Still write the spec, but inherit nothing — lean harder on the wiki and the user's answers, and record every constraint you would have inherited as a *point to clarify* instead of assuming it.
+- Write the spec to `02-DOCS/wiki/sdd/specs/<slug>.md`. Create the directory if absent.
+- Add a row under the `## Knowledge map` section of the root `CLAUDE.md` linking the new spec under the `sdd/specs` topic (additive only — never delete existing rows). Create `CLAUDE.md` if absent.
+- Log the spec's creation and any significant scoping decision to `02-DOCS/wiki/sdd/decisions.md` (append-only), so the chain keeps a trace of why scope landed where it did. This is the canonical SDD decisions log shared with `constitution` and `plan` — not the harness's own `02-DOCS/wiki/harness/decisions.md`.
+
+## Result envelope
+
+End with:
+
+```json result-envelope
+{
+  "status": "complete",
+  "executive_summary": "Spec written with open points ready for clarify.",
+  "artifact": "02-DOCS/wiki/sdd/specs/<slug>.md",
+  "next_recommended": "clarify",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": ["specify"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["Keep specs WHAT/WHY only.", "Acceptance criteria must be observable."]
+  },
+  "evidence": ["spec path exists", "proposal path if used", "open points listed"]
+}
+```
+
+## Next in the chain
+
+A spec is the input to **`clarify`**, not the finish line. End by pointing there:
+
+> "Spec written to `02-DOCS/wiki/sdd/specs/<slug>.md` with N open points. Next: run **`clarify`** to resolve them and de-risk the spec before planning."
+
+If `clarify` surfaces answers, they get baked back into this same spec file. Only once the spec is de-risked does `plan` derive the technical approach.
+
+## See Also
+
+- `../constitution/SKILL.md` — the project principles this spec inherits as constraints.
+- `../clarify/SKILL.md` — the next phase: resolves the Points to clarify and de-risks the spec.
+- `../plan/SKILL.md` — turns the de-risked spec into a technical implementation plan (the HOW).
+- `../harness/SKILL.md` — the 02-DOCS wiki + accompaniment dial + decisions log this skill honors.
+- `references/spec-template.md` — the exact section template written to `02-DOCS/wiki/sdd/specs/<slug>.md`.
+- `references/eliciting-requirements.md` — inference checklist + the one-question-at-a-time elicitation patterns.
+
+## Orientación (siempre)
+
+Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ✅ qué hiciste · 🧭 por qué · ➡️ siguiente, terminando en pregunta), calibrado al dial de `02-DOCS/wiki/harness/user-profile.md`. **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)
+

package/skills/specify/evals/README.md

@@ -0,0 +1,73 @@
+# Eval harness — `specify` skill
+
+These evals check two things: that the skill **triggers** on the right prompts
+(and stays quiet on near-misses that belong to other SDD phases or stack
+skills), and that, when loaded, it **measurably changes the output** — a real
+WHAT/WHY spec with no implementation leak, one-at-a-time questioning, the
+canonical file path, and honest open points. Cases live in `cases.yaml`.
+
+There is no shell runner. `specify` is a process skill judged on safety rails
+and judgement, so grading is done by an **agent harness** (a Claude Code agent
+with the rsc skill catalog loaded) plus a human spot-check.
+
+## What's in `cases.yaml`
+
+- `should_trigger` — prompts that MUST load `specify` (incl. Spanish and
+  non-obvious phrasings where the word "spec" never appears).
+- `should_not_trigger` — near-misses that must route to the correct sibling via
+  `route_to` (`plan`, `clarify`, `constitution`, `tasks`, `fastapi`, `design`).
+- `capability` — scenarios with a `must_include` rubric to grade with vs without.
+
+## Triggering eval
+
+Goal: the skill fires when an intent needs a spec, and never on the HOW, the
+ambiguity sweep, or project-wide principles.
+
+1. Configure an agent with the **full rsc skill catalog** available for routing
+   (the SDD phases — constitution, specify, clarify, plan, tasks, analyze,
+   implement, verify, review, ship — plus the stack/process skills: fastapi,
+   nextjs, go, postgresdb, flutter, design, marketing, presentations,
+   course-storytelling, building-agents, secure-coding, deployment, harness,
+   init) so routing competes realistically.
+2. For each `should_trigger` prompt: feed it cold, record whether `specify` is
+   the skill the agent loads. Run **3-5 trials** per prompt (fresh context).
+3. For each `should_not_trigger` prompt: confirm `specify` does NOT load and the
+   chosen skill matches `route_to`. Same 3-5 trials.
+4. Score: `triggered_correctly / total_trials` across both lists.
+
+**Pass bar: >= 90% trigger accuracy** over all prompts and trials, with **zero
+systematic false-positives** on the `plan` and `clarify` near-misses — those are
+the known traps. A prompt about an *existing* spec (architecture, or "find the
+ambiguities") must NOT pull in `specify`.
+
+## Capability eval
+
+Goal: prove the skill changes the answer, not just the routing.
+
+1. For each `capability` scenario, run it **twice**:
+   - **WITHOUT** the skill (base agent, no `specify` loaded).
+   - **WITH** the `specify` skill loaded.
+2. Grade each output against that scenario's `must_include` checklist — one
+   point per item covered. A human or grading agent marks each present / absent.
+3. Compute coverage = `items_covered / total_items` for each run.
+
+**Pass bar: WITH the skill covers >= 80% of `must_include`; WITHOUT clearly
+lower** (target a >= 30-point gap). The skill must demonstrably add: the
+no-implementation-leak discipline, one-question-at-a-time elicitation, the
+canonical `02-DOCS/wiki/sdd/specs/<slug>.md` path + Knowledge-map index,
+Given/When/Then acceptance criteria, and an honest *Points to clarify* handoff
+to the `clarify` phase. If the base answer already scores ~80%, the case isn't
+discriminating — tighten the rubric.
+
+## Notes on honesty
+
+- Trials are stochastic; report the raw fraction, not a rounded "pass".
+- The highest-signal capability check is the **no-implementation-leak** rule: a
+  correct answer describes observable behaviour and refuses to name a framework,
+  table, or endpoint — pushing those to *Points to clarify*. Treat a confident
+  spec that already designs the solution as a **capability failure** even if it
+  reads well.
+- The second-highest signal is **not over-asking**: a wall of questions, or
+  inventing answers to look finished, both fail the elicitation discipline.
+- Re-run after any edit to `SKILL.md` or its `references/` — wording changes
+  shift both triggering and rubric coverage.

package/skills/specify/evals/cases.yaml

@@ -0,0 +1,80 @@
+skill: specify
+
+# Prompts that MUST load `specify`. The skill turns a fuzzy intent into a written
+# WHAT/WHY spec at 02-DOCS/wiki/sdd/specs/<slug>.md — problem, goals/non-goals,
+# users, observable behaviour, testable acceptance criteria, points to clarify —
+# with zero implementation detail. It is NOT the technical plan (plan), NOT the
+# ambiguity sweep (clarify), NOT project-wide principles (constitution).
+should_trigger:
+  - prompt: "Write a spec for a bulk CSV import feature in our admin panel."
+    why: "Direct request to produce a specification for a feature — the skill's core job: WHAT/WHY at 02-DOCS/wiki/sdd/specs/<slug>.md."
+
+  - prompt: "I want to add magic-link login but I haven't really thought it through yet — can you help me nail down what it should actually do?"
+    why: "A fuzzy intent that needs to become a spec (behaviour + acceptance criteria) before any planning; 'what it should do' is WHAT, not HOW."
+
+  - prompt: "Especifica la feature de notificaciones por email antes de que nos pongamos a construir nada."
+    why: "Spanish 'especifica … antes de construir' is the exact specify trigger — capture the spec before implementation, in the rsc bilingual register."
+
+  - prompt: "Before we build it, capture the requirements for letting users export their data."
+    why: "Requirements capture for a feature, explicitly pre-build — the specify phase, even though the user never says the word 'spec'."
+
+  - prompt: "We just finished the project constitution. Now let's define the first feature: a referral program."
+    why: "Kicking off an SDD feature right after the constitution exists is precisely the constitution -> specify handoff this skill owns."
+
+  - prompt: "Draft a PRD for the new onboarding checklist — what it does and why, not how we'll code it."
+    why: "A PRD describing what/why and explicitly excluding the how is a spec; 'not how we'll code it' confirms the WHAT/WHY scope."
+
+  - prompt: "Everyone keeps jumping to the database design for the booking feature, but nobody has written down what it's even supposed to do. Sort that out."
+    why: "Someone jumped to HOW before WHAT is agreed; pulling it back to a behaviour/acceptance spec is the specify intervention."
+
+# NEAR-MISS prompts that must NOT load `specify`. Each routes to the genuinely
+# correct sibling. The recurring trap: anything that is the HOW (plan/stack),
+# the ambiguity sweep on an existing spec (clarify), or project-wide principles
+# (constitution) rather than the WHAT/WHY of one feature.
+should_not_trigger:
+  - prompt: "We already have the spec for magic-link login — now design the architecture, data flow, and testing strategy to build it."
+    route_to: "plan"
+    why: "A spec already exists and the ask is the technical HOW (architecture, data flow); that's the plan phase, not writing the spec."
+
+  - prompt: "Read our checkout spec and find the ambiguous bits and edge cases I haven't decided yet, then ask me about them."
+    route_to: "clarify"
+    why: "Surfacing ambiguities/edge cases in an EXISTING spec and resolving them is the de-risking clarify phase, distinct from authoring the spec."
+
+  - prompt: "Define our project's non-negotiable principles: stack canon, quality bars, and coding conventions."
+    route_to: "constitution"
+    why: "Project-wide guardrails/principles are the constitution, not a single feature's WHAT/WHY spec."
+
+  - prompt: "Build the bulk CSV import endpoint in FastAPI with Pydantic validation and tests."
+    route_to: "fastapi"
+    why: "Concrete implementation in a specific stack is build work delegated to the fastapi skill, the opposite of a no-implementation spec."
+
+  - prompt: "Design the type scale, colour palette, and layout for the onboarding checklist screen."
+    route_to: "design"
+    why: "Visual/UX design (pixels) is the design skill; specify owns the behavioural requirements, never the look."
+
+  - prompt: "Break the approved plan for the referral program into an ordered task list with done-checks."
+    route_to: "tasks"
+    why: "Decomposing an approved plan into verifiable tasks is the tasks phase; specify produces the upstream spec, not the task breakdown."
+
+# Concrete tasks the skill should guide, with a rubric to grade WITH vs WITHOUT
+# the skill loaded. A skill-guided answer holds WHAT/WHY discipline, asks one
+# question at a time, writes to the canonical path, and names open points; an
+# ungrounded answer typically leaks implementation and dumps questions at once.
+capability:
+  - scenario: "A user says: 'I want to add magic-link (passwordless) login.' There is a constitution at 02-DOCS/wiki/sdd/constitution.md but no spec yet. Produce the spec."
+    must_include:
+      - "Reads the accompaniment level from 02-DOCS/wiki/harness/user-profile.md and the constitution first, inferring everything it can before asking, then asks only scope-changing questions ONE at a time (not a batch of ten)."
+      - "Stays strictly WHAT/WHY: no framework, token format, database table, endpoint shape, email provider, library, or file path appears in the spec — implementation-laden answers are flagged as points to clarify instead of guessed."
+      - "Produces the spec sections: Problem & why, Goals, Non-goals / out of scope, Users & context, Behaviour (main + edge + error paths), Acceptance criteria, Points to clarify."
+      - "Writes testable acceptance criteria in Given/When/Then form that verify could later check (e.g. expired-link refusal, unknown-email revealing nothing)."
+      - "Writes the file to 02-DOCS/wiki/sdd/specs/<slug>.md (kebab-case slug), indexes it in the root CLAUDE.md Knowledge map under sdd/specs, and logs the spec creation to the canonical SDD decisions log at 02-DOCS/wiki/sdd/decisions.md."
+      - "Lists honest Points to clarify (e.g. link validity window, rate-limiting) as the handoff rather than inventing those values."
+      - "Ends by pointing to the clarify phase as the next step in the SDD chain."
+
+  - scenario: "A user pastes a rough one-liner: 'Let users export all their data as a download.' Show how you'd elicit and capture this without over-asking."
+    must_include:
+      - "Recovers the underlying problem/why rather than treating the feature request as the problem, and inherits any relevant constraints from the constitution."
+      - "Applies the 'would a different answer change the spec?' test and asks only the genuinely scope-changing question(s), one at a time, in the user's register."
+      - "Captures observable behaviour (what the user sees/can do) and explicit non-goals / out-of-scope rather than implementation (no file format library, storage, or job-queue detail)."
+      - "Turns answers into binary acceptance criteria and defers unresolved items (e.g. data scope, retention, format) to Points to clarify instead of fabricating decisions."
+      - "Notes that the spec is complete-enough-to-plan with open points remaining, and hands off to clarify — not to plan or implementation."

package/skills/specify/references/eliciting-requirements.md

@@ -0,0 +1,77 @@
+# Eliciting requirements — infer first, then ask one thing
+
+The whole point of this skill is to reach a complete-enough spec with the
+fewest questions. That means inferring hard before asking, and asking surgically
+when you must. This reference holds the inference checklist and the elicitation
+patterns the SKILL body summarizes.
+
+## Inference checklist — answer these from existing material before asking
+
+Run down this list using the `constitution`, the existing wiki, sibling specs,
+and the intent itself. Only what survives as unknown becomes a question or a
+*point to clarify*.
+
+- **Problem** — does the intent already state the pain, or only the wanted
+  feature? If only the feature, the problem is the first thing to recover.
+- **Primary user** — who triggers this? The constitution's ICP / users article
+  usually answers it.
+- **Trigger** — what event or need makes someone want this? Often implicit in
+  the intent.
+- **Success** — what does the user get that they didn't have before? That's a
+  goal, in outcome terms.
+- **Boundaries** — what's adjacent but deliberately excluded? Derive non-goals
+  from the constitution's scope and quality bars.
+- **Happy path** — the common-case behaviour is usually inferable from the
+  intent; write it, then test it with the user if L2/L3.
+- **Edges** — empty / none / one / many / max, concurrent, repeated, expired,
+  unauthorized. Walk these mechanically; each is a candidate criterion.
+- **Errors** — what does the user see when it fails, and what must NOT be
+  revealed? Security/privacy constraints often live in the constitution.
+
+What you genuinely cannot resolve here is exactly what `clarify` exists for.
+Naming it is the correct outcome, not a failure.
+
+## The one-question-at-a-time pattern
+
+A question earns a turn only if a *different answer would change the spec*.
+Apply this test before asking:
+
+> "If they answer A vs B, does a goal, a user, the scope, or an acceptance
+> criterion change?" — No → don't ask; infer or defer. Yes → ask, alone.
+
+Phrase by register:
+
+- **Non-technical / L3** — plain language, one concept, offer a concrete
+  example to react to rather than an open void:
+  > "When someone's link has expired, should they be able to ask for a fresh
+  > one right there, or is that a separate step?"
+- **Technical / L0-L1** — terse, decision-shaped:
+  > "Expired-link recovery in scope, or defer?"
+
+Always: ask → wait → record the answer in the relevant section → confirm at L2/L3
+→ ask the next. Never present a numbered list of ten questions.
+
+## Turning answers into testable criteria
+
+Once you have an answer, convert it immediately to a Given/When/Then so it's not
+lost as prose:
+
+```text
+Answer: "Yes, they can request a new link from the expired page."
+becomes
+Given an expired link, When the user opens it, Then they see a "request a new
+link" action that issues a fresh one.
+```
+
+If the answer is fuzzy ("it should feel fast"), do not invent a number — push
+once for a concrete figure; if none is available, file it under *Points to
+clarify* with the assumption you're carrying meanwhile.
+
+## When to stop
+
+Stop eliciting when the WHAT and WHY are complete enough that `plan` could start
+without guessing at scope. Lingering unknowns are fine — they belong in *Points
+to clarify*. Over-asking to feel thorough is itself an anti-pattern: it burns the
+user's patience and pushes them to rubber-stamp answers they haven't thought
+through. A short spec with three honest open points beats a long spec with three
+fabricated ones.

package/skills/specify/references/spec-template.md

@@ -0,0 +1,60 @@
+# Spec template
+
+Copy this into `02-DOCS/wiki/sdd/specs/<slug>.md`, fill it, and delete the
+italic guidance lines. Every line stays on WHAT and WHY — no framework, table,
+endpoint, library, file path, or algorithm. If you can't phrase it without
+naming the tech, it's a *point to clarify*, not a requirement.
+
+```markdown
+# Spec — <Feature name>
+
+> Slug: `<slug>` · Status: draft · Created: <YYYY-MM-DD>
+> Inherits: 02-DOCS/wiki/sdd/constitution.md
+
+## Problem & why
+<The pain, who feels it, and the cost of leaving it unsolved. One short
+paragraph. State the problem, not a pre-chosen solution.>
+
+## Goals
+- <What success delivers, in outcome terms. One bullet per goal.>
+
+## Non-goals / out of scope
+- <What is explicitly NOT done in THIS change — adjacent features, deferred
+  work, things a reader might assume are included. Be explicit, not silent:
+  unsaid scope becomes assumed scope.>
+
+## Users & context
+<Who acts, the situation they're in, and what they're trying to achieve.
+Real users from the constitution/wiki, not invented personas.>
+
+## Behaviour
+- Main path: <what the system does, observably, in the common case>
+- Edge cases: <empty, maximum, boundary, concurrent, repeated…>
+- Error paths: <what the user sees when it goes wrong; what is NOT revealed>
+
+## Acceptance criteria
+<Binary, observable checks. Prefer Given / When / Then. Each must be later
+checkable by `verify` and convertible to a `tasks` done-check.>
+- Given <state>, When <action>, Then <observable outcome>.
+- Given <state>, When <action>, Then <observable outcome>.
+
+## Points to clarify
+<The handoff to the `clarify` phase. Open questions, assumptions you made and
+on what basis, decisions deferred. This list being non-empty is normal.>
+- [ ] <Open question> — (assumption made: <…>, basis: <…>)
+- [ ] <Deferred decision>
+```
+
+## Field notes
+
+- **Status** moves `draft` → `clarified` (after the `clarify` phase) → `planned`
+  (once `plan` exists). Don't invent other states.
+- **Behaviour** is where HOW leaks in most. Audit every verb: "queries",
+  "caches", "calls", "stores in" are implementation. Replace with the observable
+  effect ("shows", "lets the user", "prevents", "remembers across visits").
+- **Acceptance criteria** are the contract `verify` checks at the end of the
+  chain. A criterion a human has to subjectively judge is not done — sharpen it
+  or move the soft part to *Points to clarify*.
+- **Updating an existing spec** (same slug): read it, merge new understanding,
+  keep the history of resolved clarifications visible rather than silently
+  rewriting. Never overwrite blind.