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?