ericrisco/rsc-harness / skills/specify
specify
VerifiedUse when a feature, change, or product idea is still fuzzy and must become an approved WHAT/WHY spec before any planning or code — the brainstorming front door of ASDD stage 2 (Spec). Turns a one-line intent into problem, goals, users, out-of-scope, the four ASDD questions (what the user can do, what result they get, what it must respect, how it proves it) and acceptance criteria, via frontier-round dialogue and 2-3 approaches with a recommendation, carrying zero implementation detail. Fires whenever someone jumps to HOW before WHAT is agreed, in any language. NOT the technical plan (that is `plan`), NOT the de-risking ambiguity sweep (that is `clarify`), NOT project-wide principles (that is `constitution`).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 32.2 KB |
| evals/README.md | markdown | 3.8 KB |
| evals/cases.yaml | config | 10.4 KB |
| references/eliciting-requirements.md | markdown | 5.2 KB |
| references/spec-template.md | markdown | 5.8 KB |
evals/cases.yaml
View on GitHubskill: 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 technical_level from 02-DOCS/wiki/harness/user-profile.md and the constitution first, inferring everything it can before asking, then asks only contract-changing gaps — the whole FRONTIER in one numbered round, each with its recommendation, and nothing whose answer depends on another question open in that same round."
- "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, Cost of not building it, The cheapest alternative, Goals, Non-goals / out of scope (including what an agent might add 'just in case'), Users & context, What the user can do, What result they get (against a human-approved reference), What it must respect (checked against the decisions log or the project's brain), How it proves it (what evidence remains), Behaviour (main + edge + error paths), Acceptance criteria, Points to clarify — and neither of the two doubt sections is left as a formality: 'Cost of not building it' names a concrete consequence, and 'The cheapest alternative' names something that would solve most of it without building this, plus why that is not enough."
- "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 02-DOCS/wiki/index.md under sdd/specs (never the root CLAUDE.md), and logs the spec creation to the canonical SDD decisions log at 02-DOCS/wiki/sdd/decisions.md."
- "Lists honest Points to clarify as the handoff rather than inventing values, and TYPES each one (pregunta abierta / suposición tomada / decisión diferida / área no formulable) so clarify knows whether to ask it, validate it, or leave it alone; a suposición carries its basis."
- "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 contract?' test, then splits what is left by dependency: independent gaps go out together in one round with recommendations, and any gap whose answer hinges on another still-open one is held for the next round rather than asked blind."
- "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 typed Points to clarify instead of fabricating decisions, and checks the written file against the phase's exit gate before calling it done."
- "Notes that the spec is complete-enough-to-plan with open points remaining, and hands off to clarify — not to plan or implementation."
- "After the user answers a question, folds the answer in, states what changed, shows the revised spec, and asks for approval AGAIN — it does not treat the answer as approval of the spec, including when the user picked the recommended option."
- "If told to run the whole chain up front, records the approval as autopilot rather than item-by-item, and says the spec is the artifact to review after the fact."
- scenario: "A user opens with pure enthusiasm and no problem statement: 'Tengo una idea buenísima — quiero montar un dashboard con IA que resuma toda la actividad del equipo cada mañana.' Nothing exists yet. Show the FIRST response, verbatim. Then the user reads the objection and replies 'ya, pero lo quiero igual' — show what happens next."
must_include:
- "The first response opens with a one-sentence RESTATEMENT of the intent and the STRONGEST OBJECTION the assistant can actually articulate — never a verdict on the idea's quality ('great idea', 'makes sense', 'that would be really useful') in any language."
- "The objection is sourced from something checked — the repo, the wiki, prior specs, or a named fact about the situation — not from generic priors; and if after looking there is genuinely no objection, it says so in ONE line and moves on rather than manufacturing one to look rigorous."
- "Runs the FRAME block from idea-refinement before any question round: actor, current workaround INCLUDING doing nothing, desired progress, constraints, and known-vs-assumed separated."
- "Names at least one concrete thing it went and LOOKED AT before objecting — the repo, the wiki, an existing spec, a prior decision — or says plainly that it could not check anything and that the objection is therefore weaker."
- "Enumerates 'don't build it' as one of the directions, with its concrete consequence — not mentioned as a courtesy and not silently dropped."
- "Does not turn the objection into a refusal or a question round: it states the doubt and keeps going in the same turn, so the user gets both the reservation and the progress."
- "The spec it goes on to write carries 'Cost of not building it' and 'The cheapest alternative' with real content, and the assistant notes that spec:gate will refuse the spec if either is left empty."
- "On 'ya, pero lo quiero igual': does NOT re-argue and does NOT block — it accepts the decision, and says that the reason for proceeding against the objection gets written into the spec so the record shows the doubt was seen and overridden rather than never raised."
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |