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 |
references/spec-template.md
View on GitHub# 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
---
type: spec
title: Spec — <Feature name>
description: WHAT and WHY for <feature> — problem, goals, behaviour, acceptance criteria.
tags: [sdd, spec]
timestamp: YYYY-MM-DDTHH:MM:SSZ
topic: sdd
slug: <slug>
status: draft
---
# Spec — <Feature name>
> Slug: `<slug>` · Status: draft · Created: <YYYY-MM-DD>
> Inherits: [constitution](../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.>
## Cost of not building it
<What concretely happens if nobody does this, and what it costs. If the honest
answer is "not much", that IS the finding — write it down rather than softening
it. Required for specs dated 2026-09-06 or later.>
## The cheapest alternative
<What would solve most of this WITHOUT building it, and why that is not enough.
"Nothing" is not an answer; there is always a manual workaround, a smaller
version, or doing nothing. Required for specs dated 2026-09-06 or later.>
## 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, and what an agent could be
tempted to add "just in case" (a feature nobody asked for). 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.>
## What the user can do
<The action, the starting conditions it needs, and who is (and is not)
allowed to do it. Required for specs dated 2026-11-03 or later.>
## What result they get
<The observable result, against a reference the human approved: a screenshot
or sketch for UI, the expected response for an API. An agent's own judgement
that two screenshots "look alike" is not a reference. Required from 2026-11-03.>
## What it must respect
<Constraints and prior behaviour that must keep working. Look them up in the
project's brain if it has one, otherwise in 02-DOCS/wiki/sdd/decisions.md and
the existing specs, so this spec never steps on a prior decision. Required from
2026-11-03.>
## How it proves it
<How the check runs and what evidence remains afterwards. "Yes, I tested it" is
not evidence. Required from 2026-11-03.>
## 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 typed handoff to `clarify`. Every entry declares which of the four it is,
because each one gets a different action from the next phase. Non-empty is
normal; untyped is not — an untyped entry is read as `pregunta abierta`, the
costliest of the four.>
- **pregunta abierta** — <formulable now, unanswered. clarify asks it.>
- **suposición tomada** — <what you decided.> *Base:* <why.> *Riesgo:* <what
changes if it turns out wrong.> clarify validates it rather than re-asking.
- **decisión diferida** — <sharp, out of this cycle on purpose. clarify leaves
it.>
- **área no formulable** — <you can tell something is coming and cannot phrase
the question yet. clarify notes it; it graduates when it sharpens.>
```
## Field notes
- **Status** moves `draft` → `clarified` (after the `clarify` phase) → `planned`
(once `plan` exists). Don't invent other states. An approval obtained as a
blanket "just run it" is recorded as **approved in autopilot**, not flat.
- **Before you call it written**, run `npx @ericrisco/rsc spec gate <path>`. It checks that
every section here carries content or an explicit open point, and prints the
clauses it cannot check (the unmarked assumption is yours).
- **The enforced sections are dated, not retroactive.** `Cost of not building
it` and `The cheapest alternative` are required only for specs whose
frontmatter `timestamp` is `2026-09-06` or later; the four ASDD questions
(`What the user can do`, `What result they get`, `What it must respect`, `How
it proves it`, or their Spanish headings) from `2026-11-03`. Specs written
before are exempt — they cannot answer honestly after the fact, and a gate that turns
the whole corpus red is a gate that gets switched off. A spec with no readable
`timestamp` falls on the exempt side too.
- **Sharpness, not difficulty**, sorts the last two types from the first: *can
you state the question precisely now?* Not *can you answer it?* Anything past
what this change is for goes to **Non-goals**, where it never graduates.
- **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.
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 |