idea-to-spec

name	idea-to-spec
description	Turn a rough product or engineering idea into a reviewed, implementation-ready spec through a bounded loop — frame, research, a required grill interview that challenges the idea, draft, review, revise, verdict. Use when an idea, feature request, or problem statement needs to become a durable, evidence-backed spec before implementation starts, or when a spec must be produced that a downstream done gate can later prove.
license	Apache-2.0

Idea To Spec

Turn a rough idea into a reviewed, implementation-ready spec. The output is a durable spec whose acceptance criteria a delivery loop (such as spec-to-done) can later prove. Any capable agent — or a human facilitator — can run the loop from this file alone.

Inputs

• Rough idea, problem, or opportunity.
• Known constraints, non-goals, and audience.
• Any provided context or research sources.
• The reviewer or decision-maker for the final verdict.

The Loop

frame -> research -> grill -> draft -> review -> revise -> peer review (optional) -> verdict

This is a loop, not a pipeline. Route backward whenever a step finds a gap:

From	When	Return to
research	the framed questions cannot be answered from reachable sources	frame (narrow scope) or verdict (defer)
review / peer review	a claim is unsupported or evidence is thin	research
review / peer review	intent is ambiguous or a trade-off is undecided	grill
review / peer review	the contract or criteria need rework	revise, then review again
verdict	outcome is revise / defer / reject	the matching earlier step, or stop

Conformance Rules

• The grill step is REQUIRED. It is the guard against accepting the input uncritically.
• A spec produced without a grill pass is non-conformant, even if the draft looks complete.
• A review that cannot find the grill record must return the work as non-conformant instead of accepting the spec.
• If the loop runs unattended and grill answers are unavailable, the spec must include explicit flagged assumptions. Do not silently accept unanswered questions as facts.
• Separate facts, assumptions, recommendations, and open questions.
• Keep raw source dumps, private notes, and transcripts out of the spec. Link or summarize bounded evidence instead.
• Do not invent evidence. If evidence is missing, mark the gap and route the work back to research, grill, or defer.
• Peer review is optional; skipping it when no independent second reviewer is available is conformant. Recording a peer review that never ran is not.

1. Frame

Define the decision surface before collecting evidence.

• Name the user problem in one paragraph.
• State the expected durable artifact and intended reviewer.
• List load-bearing questions where different answers would change the spec.
• Name success criteria and explicit non-goals.
• Decide what evidence is required before a draft is worth reviewing.

Exit when the scope is narrow enough that research can answer the open questions without becoming unbounded.

2. Research

Collect only the evidence needed to answer the framed questions.

• Use bounded reports with a short summary, source list, constraints, and open uncertainties. The packet contract is the JSON Schema bundled with this skill at references/research-packet.v1.json. When this kit's templates are available, the durable report is the rendered HTML built from ../../templates/research-report.html — source audit, confidence grades, and inline comments included; a plain markdown report is the fallback when the template is not available.
• Look outward, not just inward: prior art, existing solutions, and the current state of the field can invalidate the idea faster than any internal analysis.
• Name the closest existing solutions and why they do not already settle the question. Novelty is a claim that needs evidence like any other.
• Keep a source audit: where you searched, what you used, what you skipped or could not reach, and why. Coverage that cannot be audited cannot be trusted.
• Link reports from the spec instead of copying raw source material into it.
• Separate observed facts from interpretation.
• Grade each conclusion's confidence (low / medium / high) instead of presenting every finding as equally solid; mark stale or partial evidence rather than smoothing it into the conclusion.
• Stop when the framed questions are answered well enough to support a draft, or when the gap is a clear blocker.

Exit with linked research reports and a concise list of conclusions the spec will rely on.

3. Grill

This step is required. A spec produced with no grill pass is non-conformant.

The grill protects against accepting the original idea uncritically. After research — when the questions can be specific about real trade-offs — ask the operator a short set of pointed questions that would materially change the spec.

Use the grill-me skill (from mattpocock/skills) as the interview engine when it is available: one question per turn, depth-first through the decision tree, checking anything it can resolve itself before asking. Do not rebuild that engine inline. Whichever engine runs the interview, this step's contract holds — the interview happens after research, includes the kill question, and produces the grill record described below.

• Ask only load-bearing questions: a different answer must change the draft. If no answer would change anything, the question is filler — drop it.
• Include at least one kill question — "should this be built at all, given what research found?" A cheap, well-evidenced rejection is a success of the loop, not a failure.
• Prefer concrete trade-offs over broad brainstorming prompts.
• Record answers as decisions, constraints, or explicit unresolved assumptions, and trace each one to what it changed — a section, criterion, or flagged assumption in the spec. An answer that changed nothing was not load-bearing.
• If the operator cannot answer, keep the uncertainty visible in the spec.
• Do not silently turn unanswered grill questions into hidden defaults.
• A "short set" is roughly 3-8 questions: enough to expose the load-bearing decisions, not a survey.

Tailor the questions to the idea's domain:

• Engineering / library / API ideas: units and representation, ranges and overflow, rounding and precision, the error / empty / null contract, types, and edge inputs (empty, negative, huge, malformed); binary vs decimal, locale, and encoding where relevant.
• Product / process / workflow ideas: what it really solves, who is made worse off, the smallest useful version, and how you will know it worked.

Exit when the spec has either answered grill questions or clearly named the assumptions that remain.

4. Draft

Write the spec as the proposed operating contract.

• Use the durable spec shape: TL;DR, fixed linked index, Why, What, How, and Why Not. When this kit's templates are available, draft the spec as a single-file HTML built from ../../templates/spec-template.html — its fixed left index and inline-comment widget are what make the review steps work on the artifact itself. Plain markdown in the same shape is the fallback when the template is not available.

• Omit template sections the spec has no content for (and their index entries) instead of filling them with placeholders; add sections the spec needs (for example the grill record) as indexed sections.

• Include problem, goals, non-goals, proposed behavior, acceptance criteria, risks, and rollout or migration notes when relevant.

• Give every acceptance criterion a stable ID, a testable statement, and an evidence expectation:

  ID	Criterion	Evidence expectation

  These IDs are the join key a delivery loop uses for its evidence ledger — a criterion no check or artifact could ever satisfy is a drafting bug.

• Carry the grill record into the spec itself: the questions, the decisions they produced, and the flagged assumptions by name. Review must be able to find the record in the artifact, not in chat history.

• Link each major claim to bounded evidence.

• Avoid implementation trivia unless it changes the contract reviewers must approve.

The draft is a review target, not accepted truth.

5. Review

Review the draft against the frame, research, grill answers, and criteria.

The reviewer must not be the drafter. At minimum — even with one model and no collaborators — use a fresh session with no drafting context: self-review inherits the draft's blind spots.

• Confirm the spec answers the original load-bearing questions.
• Confirm the grill record exists and shows at least one answer or flagged assumption that shaped the draft.
• Check that research links are bounded and sufficient.
• Look for hidden product decisions, unverifiable criteria, missing non-goals, and unsupported claims.
• Return a structured review: a one-paragraph summary of what the spec claims (proves the reviewer read it), then required changes, optional suggestions, and open questions for the operator.
• When the spec is on the kit's HTML template, record comments directly in the artifact via its inline-comment widget — the review then travels with the document.
• Route gaps backward using the loop table: thin evidence goes to research, unresolved intent goes to grill. Do not approve a speculative spec.

6. Revise

Update the draft in response to review.

• Apply required changes directly in the spec.
• Add or update linked reports when review reveals an evidence gap.
• Record rejected suggestions with a short reason when the trade-off matters — a rebuttal, not a silent dismissal.
• A required change is resolved only when an independent reviewer verifies the fix; the drafter applying it is not resolution. Cosmetic or editorial suggestions may be applied without a fresh pass.
• Re-check that acceptance criteria still match the intended outcome.
• Keep the spec readable; do not append review transcripts or source dumps.

Return to review when required changes affect the contract or criteria.

7. Peer Review (Optional)

Run this stage on a review-ready spec — after the internal review and revise cycle has converged — and only when a genuinely independent reviewer is available: a different model, another agent, or a human. Do not spend an independent reviewer on problems the internal review would have caught.

Not everyone has access to a second model: skipping this stage is conformant. Record the skip in the review record instead of pretending the pass happened.

• Prefer reviewers with different failure modes: a different model family beats a second session of the same model, and a human beats both for taste and intent.
• Optionally convene a small panel of 2-3 peer reviewers with distinct lenses — evidence quality, feasibility, testability of the criteria.
• Peer reviewers return the same structured review form as step 5.
• One named reviewer owns the merged verdict; peer comments inform it, they do not dilute accountability.
• Peer findings route backward like review findings: required changes go to revise and must be re-verified by an independent reviewer (the peer or the internal reviewer) before verdict; editorial suggestions may be applied directly.

8. Verdict

Close with one explicit outcome.

• Accept: the reviewed spec is ready to drive implementation.
• Revise: specific changes or evidence gaps remain; return to the matching earlier step.
• Defer: the idea is valid but not ready for implementation; record the trigger that would reopen it.
• Reject: the idea should not be built; record the reason and any reusable research links.

The verdict must name the reviewed spec as the durable artifact and identify any bounded research reports it depends on.

Common Failure Modes

Failure	Counter-rule
Transcription spec: the draft restates the request in spec formatting.	The grill record must show at least one decision or flagged assumption that changed the draft.
Grill theater: soft questions no answer could change.	Every grill question is load-bearing; drop the rest.
Research dump: raw sources pasted into the spec.	The spec carries conclusions and links; reports carry the material.
Assumption laundering: unanswered questions quietly become facts.	Unanswered questions appear as flagged assumptions, in the spec, by name.
Unprovable criteria: acceptance criteria nothing could ever satisfy.	Each criterion names its evidence expectation before the spec is accepted.
Self-review: the drafter grades its own spec.	The reviewer is independent of the drafter — a different person, model, or fresh session.
Fake peer review: the record claims a peer pass that never ran.	Skipped optional stages are recorded as skipped, never silently implied.

Handback

Include the spec link, verdict, review record, linked research reports, grill questions and answers, and any open risks, waivers, or follow-up decisions.

Example

The loop-engineering-kit repository (github.com/gozhang2/loop-engineering-kit) publishes a real, attended run of this skill under examples/travel-expense-prep-agent/: the rough idea and the operator-answered grill record, the full reviewed spec and bounded research report on the kit's templates, flagged assumptions, and a peer review by a second model that found real defects.