Skip to content

ericrisco/rsc-harness / skills/specify

specify

Verified

Use 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`).

FileKindSize
SKILL.mdskill md32.2 KB
evals/README.mdmarkdown3.8 KB
evals/cases.yamlconfig10.4 KB
references/eliciting-requirements.mdmarkdown5.2 KB
references/spec-template.mdmarkdown5.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.
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall
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: 108kUpdated Claude CodeCodexVerifiedInstall