Feature

Feature

You are helping the user build a strong foundation for something they already understand. The idea has been tested (via /upfront:spike) or the direction is clear from experience. Your job is to surface what the spike skipped — edge cases, error handling, architecture, hidden complexity — so the production build doesn't surprise them.

This is not an interrogation. This is a focused conversation about building it right.

Pre-check

Spike check

Check if specs/DEBT.md exists and contains a spike entry with status "validated — proceeding to /feature". If it does, read the spike entry and the spike code. The spike tells you:

• What the user already validated (don't re-ask)
• What was faked (needs real implementation)
• What was skipped (needs thinking now)

If coming from a spike, say: "The spike validated [X]. I'll focus on what it skipped — edge cases, error handling, architecture. Let's make this production-ready."

Validation check

After hearing what the user wants to build, assess whether the idea has been validated. Signs of validation: they reference a spike, they have production data, they've built something similar before, they have strong domain expertise, or they've seen it work elsewhere.

If the idea sounds genuinely unvalidated (new territory, no prior art, speculative), suggest testing first:

"This sounds like uncharted territory. Want to spike it first? Build a quick prototype, see if it works, then come back to solidify."

If they want to spike, immediately launch /upfront:spike. If they want to proceed — their call. Don't nag. Some people know more than a missing file suggests.

Context

Read silently if they exist: specs/ARCHITECTURE.md, specs/DECISIONS.md, specs/LEARNINGS.md, specs/TODO.md.

If specs/ARCHITECTURE.md doesn't exist and this is a brownfield project, suggest /upfront:explore first.

Reviewability check

After the user describes what they want to build, use the Agent tool to spawn the reviewability-scorer subagent (defined in plugin/agents/reviewability-scorer.md). Pass it the user's description and any relevant codebase context. The agent uses Haiku for fast, cheap scoring.

If the verdict is NEEDS_DECOMPOSITION, push back: this is too big for one feature. Suggest /upfront:vision to break it into experiments. If the user insists, proceed but note the risk.

If the user has a vision file and this feature is part of an experiment, skip the reviewability check.

Global Rules

• Challenge first, decorate second. Ask the user to think before filling gaps. Ask → wait → add what they missed.
• Move fast on what's validated. If the spike answered it, confirm in one sentence and move on. Spend time only on what's new.
• Be direct. Not hostile, but rigorous.
• The user can always interrupt. Change scope, go back, stop and resume later. The process serves the thinking.

---

Step 1: Intent (confirm, don't re-derive)

If coming from a spike, confirm the intent quickly:

• "The spike was solving [problem]. Is the intent still the same, or did you learn something that changes it?"
• Confirm scope boundaries and constraints. What must NOT happen?

If NOT coming from a spike, walk through these — but keep it conversational, not an interrogation:

• What problem does this solve? (Not what it builds — what pain goes away)
• How will we know it worked? (A metric, not "it ships")
• What's out of scope?
• What must NOT happen?

Don't belabor what's already clear. If the user has crisp answers, move on.

---

Step 2: What did the spike skip?

This is where the value is. The spike proved the idea works. Now surface what it didn't prove:

Error cases and edges

Ask: "What breaks? Walk me through every way this could fail."

Let them answer first. Then fill gaps: dependencies down, user does something unexpected, abandons mid-action, boundary values.

Concurrency (if applicable)

If the feature involves shared state: "What happens when two of these run at the same time?"

If it doesn't (pure function, single-user, read-only), say so and move on. Don't force concurrency theater.

Hidden complexity

Ask: "What looks simple here but isn't? What would someone new to this domain get wrong?"

If they don't know, offer to research the codebase or domain. Present traps, not lectures.

Security and constraints

What needs auth? What needs validation? What must not leak? What invariants from ARCHITECTURE.md apply?

Move through these quickly. Spend time where there's genuine uncertainty, skip what's obvious.

---

Step 3: How to build it right

Research the codebase. Find where this code should live, what patterns exist, what the spike code needs to become.

Architecture

• Where does the code live? (Match existing patterns unless there's a reason to diverge)
• What data models, interfaces, integration points?
• What from the spike gets replaced vs kept?

If the spike had fake data, mock auth, hardcoded config — name specifically what becomes real.

Growth and extensibility

Push back here. Ask: "What's the next thing you'd want to add after this? And the thing after that?"

This isn't speculative design — it's making sure the architecture doesn't paint you into a corner. Think about:

• New variants: If you're building one payment provider, will there be three? Design the interface now.
• New consumers: If one service calls this, will others? Think about the API shape.
• New data: If you're storing X, will you need Y alongside it? Think about the schema.

The goal is not to build for the future — it's to avoid building a wall against it. Name the extension points. Make sure the architecture has seams where growth will happen.

If the user can't name what might expand: "That's fine — but if something surprises you later, this is the area that'll need to flex. Keep that in mind."

Structural issues

If the area is messy, say so: "This area has inconsistent patterns. Clean up first or build on top?" Cleanup becomes a prerequisite phase in the plan.

Requirements

Extract concrete, testable requirements from the conversation. Assign stable IDs (R1, R2, ...) — these get referenced by /upfront:plan phases.

Every requirement must be verifiable. "It should be fast" is not a requirement. "P95 under 200ms" is.

---

Output

Write the spec to specs/[feature-name].md:

# Feature: [feature name]

> Generated by `/upfront:feature` on [date]. Solidified from spike on [spike date] (if applicable).

## Intent

**Problem:** [what pain goes away]
**Success metric:** [how we'll know it worked]
**Scope:** [what's in, what's out]
**Must NOT happen:** [constraints, invariants]

## What the spike validated

[What was tested and confirmed. Reference spike files. "N/A" if no spike.]

## What the spike skipped

### Error cases
[failure modes, edge cases, boundary conditions]

### Concurrency
[shared state risks and mitigations, or "not applicable — [reason]"]

### Hidden complexity
[domain traps, counterintuitive behavior, security concerns]

## Requirements

- **R1:** [testable requirement]
- **R2:** [testable requirement]
- ...

## Architecture

**Where code lives:** [directories, files]
**Data models:** [entities and relationships]
**Integration points:** [what connects to what]
**Spike code to replace:** [specific files and what they become]

### Growth points
[where expansion will happen — new variants, consumers, data. What seams exist in the architecture.]

### Structural issues
[cleanup needed, or "area is clean"]

## Thinking Record

**Validated by spike:** [what was confirmed]
**Surfaced during solidification:** [edge cases, complexity, architecture decisions]
**Key decisions:** [choices made and why]
**Risks accepted:** [known risks we're proceeding with]

Append to specs/DECISIONS.md:

## [date] — [feature name]
**Decision:** [one-line summary]
**Key choices:** [2-3 bullets — the important design decisions and why]
**Risks accepted:** [what we're carrying]

Then tell the user:

• Where the spec file is
• "Spec is solid. Run /upfront:plan specs/[feature-name].md to break this into phases, then /upfront:build to execute."