Request To Spec Issues

Request To Spec Issues

Purpose

Convert a completed grill-change agreement record into an intent-first spec candidate and vertical TDD-ready issue briefs. Preserve product intent and decision rules so implementation choices follow the agreed direction.

Preconditions

• The grill is complete and its agreement record is approved.
• That grill approval authorizes this synthesis and one bounded local persistence step; do not ask for a second product-level approval.
• Relevant local specs, ADRs, docs, fixtures, and code context have been checked.
• If there is no completed grill agreement, stop and run grill-change first.

Synthesis Rules

1. Do not re-interview the user except on a derivation exception - a contradiction, a missing material decision, or scope expansion (see Derivation Exceptions).
2. Keep product intent, non-goals, durable terms, and hard-to-reverse decisions above implementation mechanics.
3. Preserve existing spec contracts and safety rules unless the user explicitly approved changing them.
4. Split work into vertical behavior slices, not file layers.
5. Make every issue small enough for a focused RED, GREEN, refactor loop.
6. Mark dependencies and parallel-safe work explicitly.
7. Propose architecture rescue candidates before feature slices when a change would deepen an already fragmented codebase.

Architecture Rescue Candidates

When architecture rescue is needed, propose candidates before feature issues. Each candidate must include:

• Files or modules involved
• Current friction
• Proposed deeper module or clearer interface
• Expected locality and leverage improvement
• Expected test improvement
• ADR or spec conflicts
• Recommended dependency state: prerequisite, parallel, or later cleanup

Spec Candidate

Include these sections:

• Status
• Problem
• Goal
• Intent
• Decision Rules
• Non-Goals
• User Flow
• Inputs
• Outputs
• Contracts
• Security Rules
• Acceptance Criteria
• Tests
• TDD Strategy
• Issue Plan
• Documentation Updates
• Final Review Checklist

TDD Strategy complements Tests; it must not replace the required Tests section from docs/specs/SPEC_TEMPLATE.md.

Seam & Interface Design

Decide the test seam and mock boundary now, under this human gate, so the TDD loop runs without new architecture decisions.

Classify each slice:

• computation: pure input to output; the seam is the function's return value.
• orchestration: coordinates other units; the seam is the observable effect at the boundary it drives.
• deterministic generator: input profile to emitted artifacts; the seam is the generated output compared as a fixture.

Seam rules:

• Pick the highest boundary that keeps tests fast and deterministic; prefer fewer, higher seams over many low ones.
• Prefer an existing seam over inventing a new one.
• Declare the allowed mock boundary as unmanaged dependencies only, such as network, clock, or filesystem you do not own; never mock the code under test.
• Sizing rule: one slice = one seam = one observable outcome = one RED.

Human-gate checklist to confirm before writing briefs:

1. Is the seam at the highest fast, deterministic boundary?
2. Is the unit under test treated as a black box?
3. Do inputs and outputs cross an explicit interface?
4. Are the names drawn from the glossary?
5. Does an abstraction exist only for the test?

Issue Brief Format

Each issue brief must include:

• Title
• Parent spec or request
• Intent summary
• Behavior slice
• Non-goals
• Acceptance criteria
• Expected RED proof
• Expected GREEN proof
• Seam under test
• Allowed mock boundary
• Test command guidance
• Likely file ownership
• Dependencies
• Parallelism notes
• Contract impact
• Security impact
• Documentation impact
• Implementation context
• Review expectations

Dependency States

Use these states:

• ready
• blocked
• parallel-safe
• sequenced
• human-gate

Derivation Exceptions

Grill approval covers a faithful synthesis only. Stop before any write, report the issue, and ask the human when derivation reveals a contradiction, a missing material decision, or scope expansion beyond what the grill approved. Persist nothing until the human resolves the exception. These are the only reasons to re-interview after an approved grill.

Persisted Artifacts

The approved grill already authorized this persistence, so persist workflow state in one write step without a second approval. First report what will be persisted, then, after the write, report what was persisted. All writes still go through the client's write-approval flow, and this step never implements any synthesized issue.

• TASKS.md: an index-only ledger. Each row links to a brief and carries one state from the closed set ready | blocked | sequenced | parallel-safe | human-gate | in-progress | done. Keep task content in the briefs, not the ledger.
• docs/specs/<spec-dir>/issues/NNN-slug.md: one brief per slice, using the Issue Brief Format above.
• CONTEXT.md: a glossary only, created lazily when the first durable term appears. Each definition is at most two sentences; add an Avoid: line for terms that must not be used. No implementation details or decisions.
• ADRs: record a decision that meets all three criteria - hard to reverse, surprising without context, real trade-offs. Write to the existing project ADR directory if present, otherwise docs/adr/.

Output

Return:

• Spec candidate or spec patch
• Vertical issue briefs
• Dependency map
• Parallelism map
• Human gates
• Recommended next step

Safety

• Do not upload source code.
• Do not read or print secrets.
• Do not include credentials, environment values, production data, or private endpoints.
• Do not create GitHub issues, labels, projects, or milestones.
• Do not persist before the grill agreement is approved, and stop before writes on a contradiction, a missing material decision, or scope expansion.
• Do not implement any synthesized issue; approval authorizes persistence, not implementation.
• Do not propose bypassPermissions, tool pre-approval, dependency auto-installation, hosted execution, or remote MCP behavior.