spec-to-goal

name	spec-to-goal
description	Convert a raw software requirement, feature request, PRD, issue, or vague product spec into a trackable, realistic, intent-aligned Goal Contract before implementation. Use when the user says /spec-to-goal, $spec-to-goal, spec to goal, requirement to goal, define goal, validate realism, success criteria, dependencies, or asks to clarify before coding.

Spec to Goal Skill

Use this skill to transform a raw software requirement into a realistic, validated, implementation-ready Goal Contract.

This skill is for product and engineering shaping. Do not implement code while using this skill unless the user explicitly switches to implementation after a valid Goal Contract exists.

Why this skill exists

This skill enforces three outcomes:

1. Make the goal trackable. Convert vague intent into a goal with an ID, current state, target state, success criteria, acceptance criteria, and validation plan.
2. Make the goal realistic. Validate the goal against the actual current situation: codebase, dependencies, constraints, data, risks, and available evidence.
3. Align human intent with agent execution. Translate the user's intent into a bounded contract so the implementation agent does not hallucinate objectives, invent fake evidence, or expand scope.

Core principle

A feature request is not a goal. A goal is an outcome with a current-state baseline, constraints, dependencies, success criteria, a validation method, and an implementation boundary.

Pipeline:

Raw requirement
→ Requirement intake
→ Draft goal
→ Reality validation
→ Goal Quality Gate
→ Goal Contract
→ Handoff to implementation

Required behavior

When invoked:

1. Read the user's raw requirement, referenced files, docs, issues, code, or context.
2. Identify ambiguity and missing information.
3. Inspect the repository when useful to validate the current state.
4. Convert the raw requirement into an outcome-oriented goal.
5. Validate whether the goal is realistic given current code, dependencies, team constraints, and available evidence.
6. Apply the Goal Quality Gate: trackable, realistic, intent-aligned, and classified for autonomy.
7. Produce a Goal Contract.
8. Save the contract to docs/goals/<YYYY-MM-DD>-<short-slug>.goal.md unless the user asks for chat-only output.
9. End with an exact /goal command only if the contract status is VALIDATED.

Non-negotiable rules

• Do not treat a requested feature as the goal by default.
• Do not produce implementation tasks until the goal has passed reality validation.
• Do not invent metrics. If real metrics are unavailable, mark them as assumptions and propose proxy metrics.
• Do not invent current-state evidence. Evidence must come from the repo, docs, data, logs, tests, user context, or explicit assumptions.
• Do not hide blockers. Classify blocked work as blocked.
• Do not allow vague success criteria such as “works well”, “good UX”, “fast”, or “secure” without measurable verification.
• Every VALIDATED contract must have a single, verifiable Exit criterion. Prefer a concrete number. The Exit criterion is what /goal re-checks each turn, so keep it short and unambiguous.
• Define how progress is measured. If no measurement tool exists, instruct the agent to build one as the first step of the goal. Add a guardrail metric so the target cannot be gamed (e.g. passing tests by deleting them).
• For visual goals, do not make a pixel-diff the Exit criterion. Decompose the reference into a feature checklist plus design-system adherence, and scope which assets are generated vs. reused.
• Specify the environment fidelity the goal needs. If the available environment cannot produce a trustworthy measurement, classify as NEEDS_DATA or BLOCKED rather than VALIDATED.
• Do not mark a goal AUTONOMOUS_ELIGIBLE when any acceptance criterion cannot be verified by the agent alone.
• Do not expand scope beyond the stated goal.
• If the goal is too large, split it into a smaller valid goal and list the deferred goals.
• Preserve the user's intent. Do not replace it with an agent-invented objective.

Flow nodes

1. Requirement intake

Extract:

• Raw requirement
• Request source, if known
• User or stakeholder
• Interpreted human intent
• Claimed problem
• Desired behavior
• Product area
• Existing related files, routes, APIs, DB tables, contracts, jobs, tests, docs, or analytics
• Starting points the user already knows (suspected hotspots, where to look first)
• Tools/environments available (browsers, deploy previews, profilers, datasets, test envs)
• Known constraints
• Unknowns

Ask at most three clarifying questions, and only when blocking. Every question must be decision-ready: state what you already verified, the options, what each option implies, and your recommended default. Otherwise proceed on labeled, reversible assumptions. Security, privacy, destructive, irreversible, and spend choices always go to the user; never default those.

2. Draft goal

Rewrite the requirement as an outcome.

Bad:

Build a referral dashboard.

Good:

Increase creator-driven acquisition by making referral earnings visible, understandable, and claimable from the user dashboard.

The draft goal must name:

• Who benefits
• What behavior should change
• Why the change matters
• What should not be solved yet

3. Reality validation

Validate the draft goal against reality before accepting it.

Check:

• Current state: what exists now in the product/codebase?
• Evidence: what data, logs, user feedback, tickets, docs, tests, or code proves the current state?
• Dependencies: design, backend, database, smart contract, API, auth, analytics, infrastructure, legal, ops, external services.
• Constraints: time, complexity, risk, team capacity, migration cost, performance, security, compliance.
• Failure modes: what could make the goal impossible, unsafe, misleading, or too expensive?

Dependency status must be one of:

READY | UNKNOWN | BLOCKED | NOT_NEEDED

Classify the result as exactly one of:

• VALIDATED: realistic enough to implement now.
• NEEDS_DATA: plausible but lacks required evidence or baseline.
• BLOCKED: dependency prevents implementation.
• TOO_BROAD: must be split before implementation.
• DREAM: desirable but not currently actionable.
• PROTOTYPE_ONLY: can be explored, but should not be treated as production goal.

4. Goal Quality Gate

Before creating the final contract, verify these gates.

Trackability gate

The goal must have:

• Goal ID
• Current state
• Target state
• A single verifiable Exit criterion (prefer a number)
• Success criteria
• Acceptance criteria
• Validation plan
• Measurement source or proxy measurement
• Progress measurement tooling (existing or to-be-built) and a guardrail metric

If the goal cannot be measured at all, it is not VALIDATED. If the Exit criterion cannot be checked cheaply and unambiguously after a turn, tighten it until it can.

Reality gate

The goal must be grounded in current situation and dependency status.

Required:

• Current-state evidence
• Dependency list with status
• Constraints
• Environment fidelity: the stack, flags, data, and deploy/test access the goal needs, plus known gaps vs. production
• Risks and mitigations
• Clear decision: proceed, block, split, downgrade, or prototype only

If the agent cannot verify the current situation, do not pretend it is verified. If the available environment cannot produce a trustworthy measurement of the Exit criterion, classify as NEEDS_DATA or BLOCKED instead of VALIDATED.

Intent-alignment gate

The goal must constrain execution.

Required:

• Interpreted human intent
• Assumptions
• Non-goals
• Implementation boundary
• Anti-hallucination checks

Anti-hallucination checks must include:

• Which claims are supported by evidence
• Which claims are assumptions
• Which parts must not be implemented
• Which dependencies must not be assumed ready

Autonomy gate

Decide whether the goal may run unattended and record the result as the execution mode.

Mark AUTONOMOUS_ELIGIBLE only when all are true:

• The implementation boundary is bounded and needs no new product decisions.
• Every acceptance criterion is objectively checkable by the agent alone: a command with an exit code, an observable behavior, or a concrete artifact.
• The validation plan is runnable without missing credentials, accounts, devices, or human-only steps.
• No security, privacy, destructive, irreversible, or spend decision remains inside the boundary.

Otherwise mark HUMAN_PAIRED: the goal may still be implemented, but only with the user in the loop, never unattended.

5. Goal Contract

Create a Goal Contract using this structure. Status at creation is one of the six validation states; IN_PROGRESS, DONE, and REVISED are set later by the implementing agent:

# Goal Contract: <goal name>

## Status
<VALIDATED | NEEDS_DATA | BLOCKED | TOO_BROAD | DREAM | PROTOTYPE_ONLY | IN_PROGRESS | DONE | REVISED>

## Execution mode
<AUTONOMOUS_ELIGIBLE | HUMAN_PAIRED>

## Goal ID
<YYYY-MM-DD-short-slug>

## Raw requirement
<original request>

## Interpreted human intent
<what the user is actually trying to achieve, in plain language>

## Goal
<one outcome-oriented goal statement>

## User / stakeholder
<who benefits and who owns the outcome>

## Current state
<what happens today>

## Current-state evidence
- <code/doc/data/user evidence>

## Target state
<what should be true after implementation>

## Exit criterion
<single verifiable condition that means DONE; prefer a number; what /goal re-checks each turn>

## Trackability
- Measurement source: <analytics event/log/test/manual QA/proxy>
- Baseline: <known value, unknown, or assumption>
- Target: <target value or observable condition>
- Observation window: <when success can be evaluated>

## Progress measurement tooling
- Tool/command: <existing tool, or instruction to build one first>
- How to run: <exact command(s)>
- Re-run cadence: <every checkpoint / before each commit / before done>
- Guardrail metric: <metric that must not regress while chasing the target>

## Success criteria
- <measurable business/product criterion>
- <measurable user-behavior criterion>
- <measurable technical/quality criterion>

## Acceptance criteria
- <specific behavior that must work>
- <specific edge case>
- <specific regression that must not happen>

## Visual reference handling (if applicable)
- Feature/element checklist: <discrete elements that must exist and behave>
- Design-system adherence: <tokens/components/spacing rules>
- Assets to generate vs. reuse: <scope of icons/images; avoid rabbit-holing>

## Non-goals
- <explicitly out of scope>

## Dependencies
| Dependency | Status | Evidence | Risk |
|---|---|---|---|
| <dependency> | <READY/UNKNOWN/BLOCKED/NOT_NEEDED> | <evidence or assumption> | <risk> |

## Constraints
- <technical/business/time/security/legal constraint>

## Environment fidelity
- Required environment: <stack, runtime, flags, data needed for real progress>
- Access available: <deploy/test/preview access the agent has>
- Known gaps vs. production: <differences that limit or invalidate measurements>

## Assumptions
- <assumption and how to verify it>

## Risks and mitigations
- Risk: <risk>
  Mitigation: <mitigation>

## Implementation boundary
<minimal scope that should be implemented>

## Starting points & guidance
- Where to start: <files/modules/services to inspect or change first>
- Suggested approach hints: <known hotspots or strategies; "" if none>
- Allowed tools: <browsers, deploy commands, profilers, datasets>
- Acceptable shortcuts/limitations: <what the agent is permitted to do>

## Anti-hallucination checks
- Supported facts: <facts grounded in evidence>
- Assumptions: <claims not yet verified>
- Do not implement: <non-goals/scope boundaries>
- Do not assume ready: <unknown or blocked dependencies>

## Validation plan
- Pre-implementation checks: <commands/files/data to inspect>
- Implementation checks: <tests/lint/typecheck/build>
- Post-release checks: <analytics/logs/manual QA>

## Finalization checklist
- [ ] Exit criterion met and verified with the measurement tooling
- [ ] Guardrail metric did not regress
- [ ] Dead-end experiments and debug scaffolding removed
- [ ] Reflected on attempts; kept only the working approach
- [ ] `/review` run on the final diff
- [ ] progress.md updated with the final result

## Decision
<why this should proceed, be blocked, be split, or be downgraded>

## Suggested Codex /goal command
```txt
/goal Implement docs/goals/<goal-id>.goal.md. Treat the contract as law: do not edit its goal, Exit criterion, success criteria, acceptance criteria, non-goals, or implementation boundary. Start from the Starting points & guidance. Work in checkpoints: commit at each meaningful step and keep docs/goals/<goal-id>.progress.md updated. Do not expand non-goals and do not regress the guardrail metric. Stop only when the Exit criterion is met (verified with the Progress measurement tooling) and the Finalization checklist passes. End in exactly one closeout state recorded in the goal file: DONE with evidence for every acceptance criterion, BLOCKED with the exact missing item or a decision brief after all autonomous work is finished, or REVISED when the contract no longer matches reality.

Closeout

Filled by the implementing agent. Append one entry per run; never leave a run unrecorded.

• Date:
• Final status: <DONE | BLOCKED | REVISED>
• Acceptance evidence:
  • -> <command and output, or observed behavior>
• Checks not run or waived: <check + reason or explicit user waiver, or "none">
• Blocker or decision brief: <exact missing item, decision brief, or "none">

### 6. Handoff

If the Goal Contract status is `VALIDATED`, produce a concise implementation handoff:

- goal file path
- execution mode
- exit criterion (the one condition that means done)
- starting points & guidance
- progress measurement tooling and how to run it
- validation commands
- suggested `/goal` command

Recommend an unattended run only when the execution mode is `AUTONOMOUS_ELIGIBLE`.

If the status is not `VALIDATED`, do not produce an implementation command. Produce the smallest next action required to make it valid.

## Output style

Be direct. Separate facts from assumptions. Prefer concrete checks over abstract advice. Use tables only when they reduce ambiguity.