Spec Explore
Use this skill for the exploration phase of the spec-driven workflow.
Instructions
You are exploring one decision boundary in an existing project spec. Most sessions should focus on one unresolved decision, but you may handle a small cluster of tightly coupled subquestions together when separating them would force artificial back-and-forth or prevent a stable contract from being written.
The user will reference a decision, by ID or topic, and a spec file. Read the full spec file first. Treat resolved decisions as additional constraints.
Exploration
This is a deep exploration, not a forced choice. Investigate the decision space thoroughly: surface options, examine tradeoffs, challenge assumptions, research unknowns. Follow wherever the conversation leads.
When helpful, inspect the codebase, current interfaces, or small factual constraints to collapse fake uncertainty. Treat lightweight evidence gathering as part of exploration, not as a separate stage.
A decision may take multiple sessions to reach its final form. Treat the user as an active collaborator in the exploration, not as someone you silently decide for. Do not turn the spec into an implicit recommendation log while the decision is still open.
Drive the exploration in the open. Present the current option space to the user, explain the important tradeoffs in concrete terms, identify what is still unknown, and use that to move the discussion forward. Do not reduce the interaction to a hidden analysis followed by a recommendation, and do not reduce it to an interview that only asks the user questions without helping structure the decision.
At the start of each exploration response, briefly re-orient the user before discussing new progress. Do not assume they remember the decision from its ID or from prior sessions.
When helpful, summarize the main options on the table, explain what each one buys and costs, point out which assumptions or open questions separate them, and ask targeted follow-up questions that help narrow or deepen the exploration. A decision may take multiple sessions to reach its final form. Keep the spec current as you go — see Updating the Spec below.
Decision Scrutiny Protocol
Use this as a baseline for evaluating any option that surfaces during exploration:
1. Justify the Decision
Start boring and treat every additional layer, service, or abstraction as a cost that needs a hard justification, not just a potential benefit.
The goal is the thinnest possible version that works end to end. "Industry standard" and "typical for this kind of project" are not justifications, only stated goals are.
Ask: "What is the cost of adding this later if it turns out we need it?" Then stress-test from both directions:
- "If I include this and it turns out unnecessary, what did it cost me?" (e.g. complexity, time, coupling, maintenance burden)
- "If I skip this and it turns out I needed it, what does recovery look like?" (e.g. hotfix at 2 AM? trivial follow-up PR? painful data migration?)
Include now if skipping is disproportionately painful to recover from. Otherwise, defer. When in doubt, do less.
2. Simplicity Challenge
Ask: "Is there a way to achieve the same outcome with fewer moving parts, fewer abstractions, or by leveraging what already exists?"
- Prefer convention over configuration.
- Prefer stdlib/framework builtins over custom implementations.
- Prefer a single well-known dependency over a clever composition of three.
- Prefer one file that does the thing over five files that organize the doing of it.
If you find yourself reaching for a pattern, ask: "Am I solving a problem I'm looking at, or a problem I'm imagining?"
3. Roads Not Taken
For each rejected option that had a simpler alternative, write one sentence explaining why the simpler option didn't cut it. If you can't write that sentence, take the simpler option.
Ground Rules
- "We might need this later" is not a justification. Solve what you've been asked to build.
- If two options are roughly equivalent, pick the one with fewer concepts to explain to a new reader.
- If you catch yourself writing "this adds flexibility" without naming a concrete scenario, that's a smell. Cut or defer.
- Reversibility matters: prefer decisions that are cheap to change over ones that are "optimal" but lock you in.
Updating the Spec
As the exploration progresses, update the decision section in the spec file whenever the user makes a call on something: a direction chosen, an option ruled out, a constraint discovered. Keep it current so the next session can pick up where this one left off. Remove stale or superseded options, questions, and assumptions as the exploration evolves.
If an open thread would not materially change the implementation contract, do not leave it behind as a blocking unresolved decision. Record it instead as an explicit assumption, accepted risk, deliberate limitation, or Future Ideas item, whichever best matches the user's intent.
Use the spec's Future Ideas section for ideas the user explicitly wants to defer beyond the initial implementation. That section is for "not now, but don't forget this" items that are explicitly out of scope for the initial implementation. It is not a substitute for unresolved decisions that still need to be answered before implementation can start safely.
Do not infer that a session has "ended" and then write a speculative summary. The trigger for updating the spec is progress in the exploration that the user has actually made or confirmed, not the agent's guess that the conversation is wrapping up.
Before a decision is settled, record only unresolved exploration state: options discussed, tradeoffs examined, assumptions the user wants to keep in play, factual constraints verified from the spec/codebase/research, open questions, and decisions or eliminations the user explicitly made. Avoid wording that implies an unresolved direction has been chosen unless the user explicitly endorsed it.
If you believe the exploration has produced enough evidence to resolve the decision, say so explicitly to the user and ask whether to resolve it now or continue exploring. Do not mark the decision settled without that confirmation.
Before marking a decision resolved, do a quick omissions check: compare the resolved section against the conversation and make sure anything the user settled that materially affects the contract is reflected in the spec.
Before marking a decision resolved, make sure the spec captures the assumptions that make the decision safe, not just the chosen shape. If the user is accepting a limitation rather than solving it, record that explicitly so fortify does not have to rediscover it as missing state.
At minimum, capture any material:
- trust boundary
- ownership boundary
- operational boundary or supported capacity envelope
- accepted risk or deliberate non-goal
- dependency on another decision whose future outcomes must not invalidate this one
When the user approves exact contract wording or structure, record it verbatim in the resolved spec. Do not paraphrase, summarize, normalize, or omit any part of it unless the user explicitly asks for a rewrite.
Interdependent decisions are normal. Do not block resolution of the current decision merely because a future or adjacent decision may extend, refine, or constrain it later. First ask whether the current decision can define a stable contract, boundary, default, or invariant that remains valid across the plausible outcomes of the other decision. If yes, resolve the current decision now and record the dependency explicitly. Only treat another decision as blocking when different outcomes there would materially change the core contract being settled here, rather than adding optional detail or a later extension point.
When the user considers the decision settled, mark it ✅ in the table only once the section reflects the final resolution clearly enough for the next session to treat it as a constraint, including the assumptions and boundaries that keep the resolution safe.
Once a decision is settled, keep that decision section focused on the resolved contract and constraints only. Do not leave "deferred follow-up" or other unresolved exploration notes inside the resolved decision section. Instead, move each remaining open thread to the unresolved decision that owns it, create a new unresolved decision if no owner exists yet, or move it to Future Ideas if the user explicitly decided it belongs after the first implementation.