Brutal Spec

Turn a decision-complete requirements brief into the behavioral and technical contract that implementation tickets will inherit. Do not publish artifacts.

Verify The Inputs

Read the requirements brief, relevant repository instructions, domain glossary, ADRs, affected interfaces, tests, and any linked research, prototype, or completed investigation map. Return unresolved material decisions to brutal-grill; do not hide them as assumptions.

Draft The Specification

Write only the contract an implementer needs. Reuse the requirements brief by reference instead of restating it, combine related material, and omit sections that do not change implementation. Use this compact shape:

## Outcome And Scope
## Behavior And Boundaries
## Interfaces, Data, And Migration
## Implementation Decisions
## Verification And Acceptance
## Risks, Assumptions, And Domain Documentation

State public interface, schema, migration, and wire-format changes precisely. Prefer stable module and domain names over file paths. Include a code or type snippet only when a prototype established a decision more precisely than prose.

Choose the highest existing public seams that can verify the behavior. Keep the number of seams small, explain any new seam, and name exact repository commands that will verify the finished work.

Propose a glossary edit when planning resolves domain language. Propose an ADR only when the decision is hard to reverse, surprising without context, and the result of a genuine tradeoff. Do not edit either document yet.

Stress-Test The Draft

When independent reviewers are available, review the same draft and evidence from these perspectives:

• architecture, module depth, and coupling
• data model, compatibility, and migration safety
• public interface, UX, and integration behavior
• reliability, security, operations, and delivery risk

Classify findings as PLAN BLOCKER, IMPLEMENTATION NOTE, or SUGGESTION. Validate each finding against the repository, fold valid notes into the draft, and return every simultaneously answerable validated blocker to brutal-grill in one round. Defer a blocker when another answer can change its necessity, wording, or options; never expose an unvalidated finding as a user question.

Approval Gate

Present outcome, scope, key decisions, material risks, and acceptance criteria as the compact approval view. Keep that view to one short paragraph and at most seven bullets total; group related decisions, risks, and criteria. Show the complete revised specification only when the user asks for it or the specification text itself is the requested deliverable. The stage completes only when the user approves and no PLAN BLOCKER or open material decision remains. Return the approved full specification to the calling skill without persisting it.