# New Spec

> Create a new spec through Socratic interview, filling each template section to zero ambiguity

- Skill: `a16z/new-spec` (Agent Skill)
- Install (CLI): `npx skillmds@latest add a16z/new-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/a16z/new-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: a16z (https://skillmd.com/u/a16z)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/a16z/new-spec

---


Create a new spec file in `specs/` by interviewing the user to fill each section of the template. The goal: produce a spec that would pass `/analyze-spec` with zero ambiguity on the first try.

## Steps

### 1. Initialize

1. Validate the argument: must be lowercase alphanumeric with dashes (e.g. `streaming-prover`). Reject otherwise.
2. Get the GitHub username: run `gh api user --jq .login`.
3. Get today's date in `YYYY-MM-DD` format.
4. Read `specs/TEMPLATE.md` to understand the required sections.
5. Read `jolt-eval/README.md` to understand the eval framework — you'll reference it when prompting the user about mechanical verifiability.
6. Explore the codebase to understand what areas the feature name suggests — run an `explore` agent to gather context. This informs your questions.

### 2. Interview — Section by Section

Walk through each template section with the user. For each section, ask targeted questions until you have enough to write it with zero ambiguity. Do NOT move to the next section until the current one is clear.

**One question at a time. Never batch.**

#### Summary
Ask: "In one paragraph, what problem does this solve and why does it matter?"

#### Intent — Goal
Ask: "What are we building? Can you state the primary objective in one sentence?" Follow up on abstractions, types, boundaries if unclear.

#### Intent — Invariants

Before asking the user anything, form a hypothesis from the Summary and Goal:
1. Read `jolt-eval/src/invariant/` (listed in `jolt-eval/README.md`). For each existing invariant, judge whether this feature is likely to touch it. If yes, note whether the feature looks like it should *preserve* the invariant as-is or *modify* it (e.g., extend input type, change the reference implementation).
2. Independently, imagine the binary properties that would have to hold for the Goal to be "correct." Which of those are not yet covered by an existing `jolt-eval` invariant? Each is a candidate for `/new-invariant`.

Present the hypothesis to the user in one pass:
```
Based on the Summary and Goal, I think this feature likely:
- May need to modify: {existing invariant Z — because ...}
- Warrants new invariants: {A — "...", B — "..."}

Does this match your intent? What would you add, remove, or change?
```

Then follow up with the open-ended prompt: "What other properties must always hold? What would break if the implementation is wrong?"

For any new properties the user adds that don't map to an existing `jolt-eval` invariant but look amenable to mechanical verification, ask: "your invariant 'X must equal Y' looks like a candidate for `/new-invariant` — want to capture it so it's mechanically checked during `/implement-spec`?"

Record changes to existing `jolt-eval` invariants and any new ones to add in the "Invariants" section of the template.

#### Intent — Non-Goals
Ask: "What is explicitly out of scope?" Push back if non-goals are vague — "you said 'not performance-critical', but the hot path in `crates/jolt-poly/` multiplies across thousands of rounds. Is there a concrete budget?"

#### Evaluation — Acceptance Criteria
Ask: "What test would prove this works? Give me concrete, checkable criteria." Each criterion must be a checkbox item. Push for specificity — "existing tests pass" is not enough; ask what NEW tests are needed.

#### Evaluation — Testing Strategy
Ask: "Which existing tests must keep passing? What new tests are needed? Does this need both `--features host` and `--features host,zk` coverage?"

#### Evaluation — Performance

Before asking the user anything, form a hypothesis from the information collected so far:
1. Read `jolt-eval/src/objective/` (listed in `jolt-eval/README.md`). For each existing performance objective, judge whether this feature is likely to move it, and in which direction.
2. Independently, imagine what "success" looks like as a measurable quantity. If it is not captured by an existing performance objective, this may be a candidate for `/new-objective`.

Present the hypothesis to the user in one pass:
```
Based on the Summary, Goal, and Invariants, I think this feature likely:
- Moves existing objectives: {X — direction, rough magnitude}, {Y — ...}
- Warrants new objectives: {A — "...", B — "..."}

Does this match your expectations? What would you add, remove, or change?
```

Then follow up with the open-ended prompt: "Beyond these, are there other performance expectations? Benchmarks, memory budgets, throughput targets? Or is 'no regression' sufficient — and if so, which benchmark verifies that?"

For any new expectations the user adds that don't map to an existing `jolt-eval` objective but look measurable, ask: "should we add a new objective via `/new-objective` so the optimizer can track it?"

Record both changes to existing `jolt-eval` objectives and any new ones to add directly in the "Performance" section.

#### Design — Architecture
Ask: "How does this fit into the existing system?" Use codebase exploration to suggest which modules are affected. Ask about type parameters, trait implementations, module boundaries.

#### Design — Alternatives Considered
Ask: "What other approaches did you consider? Why this one?" If the user says "none", probe: "What's the simplest approach that could work? Why isn't that sufficient?"

#### Documentation
Ask: "Does this need Jolt book (`book/`) changes? New pages, updated sections, diagrams?"

#### Execution (optional)
Ask: "Any implementation direction you want to capture? Algorithmic approach, optimizations, modules to touch? Or should the implementer derive this from intent and evaluation?"

#### References
Ask: "Any papers, issues, PRs, or prior art to link?"

### 3. Write the Spec

Once all sections are filled, create `specs/<feature-name>.md` with the template fully populated:
- `[Feature Name]` → feature name from the interview
- `Author(s)` → `@<github-username>`
- `Created` → today's date
- `Status` → `proposed`
- `PR` → empty (filled by GitHub Action)
- All sections filled from interview answers

### 4. Review with User

Show the complete spec to the user. Ask: "Does this capture everything? Anything to add or change?" Make edits until the user is satisfied.

### 5. Next Steps

Print:
```
Spec created: specs/<feature-name>.md

Next steps:
1. Review the spec above
2. Open a PR — a GitHub Action will add the `spec` label
3. Add the `claude-spec-review-request` label for external analysis, or run `/analyze-spec` locally
```

Do NOT modify `TEMPLATE.md` itself.