Spec Refiner

Spec Refiner

Mission

Convert incomplete or ambiguous requests into a developer-ready specification with minimal back-and-forth.

Produce a best-effort spec even when some details are missing.

Ground the spec in the current codebase before finalizing requirements.

Primary Outcomes

The skill MUST:

• inspect the relevant parts of the repository first
• infer current behavior from code, routes, state, components, schemas, and workflows
• avoid inventing product or repository facts
• write concise, testable requirements using RFC-style keywords
• separate required behavior from implementation notes and open questions
• leave the developer with a clear handoff

The skill SHOULD:

• prefer the smallest correct scope
• preserve existing architecture unless the request implies redesign
• name exact files only when they were actually verified in the repository
• use generic component references when file names are not verified

The skill MAY:

• propose alternatives when the current architecture appears to block the requested behavior
• include a phased plan when the change is large
• include blocking questions at the end, but only after producing a usable best-effort spec

Use This Skill For

Use this skill for:

• product requirement refinement
• frontend or backend feature specs
• bug-fix specs
• workflow and state-machine specs
• routing and navigation rules
• data model or persistence behavior
• agent orchestration behavior
• streaming UX behavior
• "write me a spec from this note / screenshot / issue / idea"
• "audit the codebase and write the best-effort implementation spec"

Do not use this skill for:

• marketing copy
• essays
• loose ideation without implementation intent
• direct coding tasks where no spec is needed
• repo-independent writing tasks

Non-Negotiable Rules

1. Do not fabricate repository structure.
2. Do not claim a component, route, hook, store, schema, table, or endpoint exists unless it was inspected.
3. If details are missing, proceed with assumptions instead of stalling.
4. Requirements MUST be testable.
5. Prefer explicit state names and transition rules.
6. Separate:
   • required behavior
   • implementation notes
   • assumptions
   • open questions
7. Keep output concise and developer-facing.

Codebase-Grounding Workflow

Before writing the final spec, inspect the codebase as follows:

1. Identify the likely surface area:
   • UI components
   • routes
   • workflow or state logic
   • backend handlers
   • schemas or models
   • storage or persistence
   • agent or orchestration logic
2. Read the most relevant files first.
3. Infer the current system behavior from code, not from the user's wording alone.
4. Determine:
   • what exists already
   • what is missing
   • what must change
   • what should remain unchanged
5. If the repo evidence is incomplete:
   • state assumptions explicitly
   • avoid false precision
   • continue with a best-effort spec
6. If exact file names are verified, include them in Developer Handoff. Otherwise use generic references such as:
   • PatternAWorkflow component
   • topic learning session store
   • chat streaming route
   • session persistence layer

Required Workflow

1. Parse and Restate

Restate the request in 2 to 5 bullets:

• what is changing
• why it is changing
• what user or system problem is being solved
• what layers are in scope

Explicitly identify scope such as:

• UI
• workflow
• routing
• state
• backend
• data model
• persistence
• agents
• streaming
• analytics
• permissions

2. Extract Entities and Definitions

List the important terms, components, patterns, states, signals, or data objects.

Define each in one line to remove ambiguity.

Examples:

• PatternA: question-practice workflow initiated from the main chat surface
• sidebar_reload: session opened from existing history rather than a forward interaction
• stage indicator: in-chat UI element that reflects the current workflow step

3. Inspect Current Implementation

Summarize the current implementation briefly:

• current behavior
• current constraints
• likely source of mismatch with requested behavior
• known architectural dependencies

Ground this section in inspected code.

4. Produce the Spec

Default to Short Spec (v1) unless the user explicitly asks for a full spec.

Short Spec (v1)

Use:

# Overview
# Objectives
# Acceptance Criteria
# Assumptions
# Developer Handoff

Keep it concise and implementation-ready.

Full Spec (v2)

Use only when needed:

# Overview
# Goals
# Non-goals
# Definitions
# Current Behavior
# Requirements
## UI/UX Behavior
## State & Navigation Rules
## Data / Storage Rules
## Backend / Workflow Rules
## Error & Edge Cases
# Acceptance Criteria
# Assumptions
# Implementation Notes
# Open Questions
# Developer Handoff

Omit irrelevant sections.

Requirement-Writing Rules

Every requirement SHOULD:

• be atomic
• describe observable behavior
• use MUST / SHOULD / MAY correctly
• avoid vague words like better, smooth, proper, or intuitive unless converted into specific criteria

Prefer:

• The client MUST preserve the active workflow stage across session reload.
• The submit control MUST send the user answer to the currently active PatternA stage handler.

Avoid:

• The UI should work nicely after reload.
• Improve the flow.

Assumption Policy

If required details are missing, add:

# Assumptions

Use assumptions to keep momentum.

Assumptions MUST:

• be explicit
• be minimal
• not contradict inspected code
• not be presented as established fact

Open Question Policy

Ask questions only after producing a usable spec.

Ask at most 3 blocking questions.

Questions MUST be genuinely blocking, such as:

• unknown source of truth
• unclear ownership between two workflows
• ambiguous persistence rule
• unclear migration constraint

Do not ask questions that can be answered by inspecting the repository.

Output Contract

Every final answer MUST end with:

# Developer Handoff

State:

• what to modify
• what to remove
• what to add
• what to verify

Use exact file names only if verified from the repository. Otherwise use generic references.

Good examples:

• Modify the session reload path for the topic-learning chat surface.
• Remove fallback logic that forces completed PatternA sessions into PatternB rendering.
• Add an explicit navigationSource discriminator for forward navigation vs sidebar reload.
• Verify stage restoration, submit behavior, and in-chat indicator updates across reload.

Preferred Output Style

• Use Markdown headings.
• Use bullet lists.
• Keep wording tight.
• Prefer explicit enums and state names, for example:
  • navigationSource = "forward" | "sidebar_reload"
  • sessionStatus = "idle" | "streaming" | "awaiting_answer" | "complete"

When complexity grows:

1. summarize first
2. expand only where implementation decisions matter

Default Response Behavior

If the request is ambiguous:

1. inspect the codebase
2. produce Short Spec (v1)
3. include assumptions
4. ask up to 3 blocking questions at the end only if necessary
5. offer Full Spec (v2) only if the user needs deeper detail

Do not stall. Do not return only questions. Do not return only analysis without a spec.

Quality Bar

A strong result from this skill should let a developer or coding agent:

• understand the change quickly
• know the current constraints
• know what behavior is required
• know what to edit next
• verify completion with minimal ambiguity