Goal first

Goal-First

Overview

When someone asks to build an artifact, the artifact is a guess at a solution, not the goal. The real goal is the decision or outcome the artifact is meant to drive. Build the wrong thing well = wasted work.

Core principle: interrogate the decision before the artifact. The requested artifact may be the wrong artifact.

This skill runs a goal interview, writes a charter, then drives delivery in small buckets with checkpoints and explicit drift checks.

When to Use

• User names a thing to build before stating why ("build a dashboard / bot / pipeline / report")
• Scope vague or success undefined
• You feel the pull to ask "what tech? where's the data? which features?" first — that pull is the signal to use this skill instead

When NOT to use: user already has an approved spec/plan (use writing-plans/executing-plans), or task is a small well-defined edit.

The Iron Rule

No solution questions until goal + core decision are written and confirmed.

Solution questions = tech stack, data source, features, UI, libraries, architecture. All forbidden in the interview. They presume the artifact is correct. First find out if it is.

Process

1. Goal interview (no code, no solution talk)

Ask, one cluster at a time, plainly. Goal is to surface:

• Outcome: What changes in the world if this succeeds? What can you do after that you can't now?
• Core decision: What recurring decision or action is this meant to drive? (e.g. "which vendor to cut", "whether to deploy", "is the model drifting") — the artifact exists to make THIS better.
• Current pain: How is the decision made today, and why is that bad?
• Success signal: How will we know it worked — one observable thing.
• Anti-goal: What is this explicitly NOT for? (bounds scope, prevents drift)

Stop when you can state the core decision in one sentence. Don't interview past that — over-interviewing is its own failure.

2. Write the charter

Write PROJECT_CHARTER.md (or <project>-charter.md if naming collision) in the working dir:

# <Project> — Charter

## Goal
<one sentence: the outcome>

## Core decision this drives
<one sentence: the recurring decision/action made better>

## Today's pain
<how it's done now, why it's bad>

## Success signal (completion condition)
<one observable, testable thing that proves it worked — phrased so a tool can verify it>

## Anti-goals (NOT this)
- <out of scope>

## Buckets
| # | Slice | Done when (testable) |
|---|-------|----------------------|
| 1 | <smallest end-to-end slice that tests the core decision> | <observable check> |
| 2 | ... | ... |

The Success signal and each bucket's Done when are completion conditions in the official /goal sense — testable and observable, not aspirational. Write them so a tool (test run, build, file check, query) can confirm them.

• Good: "all tests in tests/ pass", "the report renders with a non-empty value for every row", "make build exits 0".
• Bad: "the dashboard is better", "performance improved", "it works well".

Confirm the charter with the user before any bucket. This is checkpoint zero.

3. Buckets — small, agile, one at a time

• Each bucket = smallest slice that produces reviewable output and moves the core decision forward.
• First bucket should test the riskiest assumption, not the easiest plumbing.
• For each bucket, before building: present a 2–4 line plan (what, why it serves the core decision, what user reviews) plus the testable Done-when.
• Build it.
• Checkpoint: show output, stop, wait for review. Do not start next bucket unsolicited.

3a. Handoff to /goal (optional autonomous execution)

goal-first clarifies WHAT/WHY; the built-in /goal command executes autonomously until a completion condition is met. Once a bucket's plan is confirmed and its Done-when is testable, you can hand it to /goal instead of building turn-by-turn:

/goal <bucket scope with file paths + concrete changes>. Done when <bucket's Done-when>.

Rules for a clean handoff:

• Only hand off a bucket whose Done-when is tool-verifiable — /goal needs to check its own work. A vague Done-when makes /goal run blind.
• Include scope (which files/dirs), the concrete change, and the completion condition in one line — same structure the official command expects.
• The checkpoint still applies: /goal stops at its completion condition; review before releasing the next bucket. Don't chain buckets into one /goal run — that skips the review the charter exists to enforce.
• If a bucket's Done-when isn't testable yet, it's not ready for /goal. Sharpen it or build that bucket by hand.

4. Drift checks — verify decisions explicitly

At each checkpoint and whenever a choice arises, restate the link out loud:

"This serves <core decision>. Still the goal?"

If a request or your own idea doesn't trace to the core decision, name it: "This doesn't tie to <core decision> — add it, or skip it?" Don't silently absorb scope.

Red Flags — STOP

• Asking about tech/data/features before charter written → stop, run the interview
• Proposing a concrete build ("I'd use Streamlit...") before goal confirmed → stop
• Assuming the named artifact is the answer (dashboard might really be an alert, a report, or a deleted process) → question it
• Building bucket 2 before bucket 1 checkpoint cleared → stop, checkpoint first
• Charter has features but no core decision → incomplete, find the decision
• Success signal / Done-when is aspirational ("works well", "is better") not testable → rewrite as an observable check before any build or /goal handoff

Common Mistakes

Mistake	Fix
Treating the requested artifact as the goal	Artifact is a hypothesis; goal is the decision it serves
Solution questions in the interview	Forbidden until charter confirmed
Over-interviewing	Stop once core decision fits one sentence
Big-bang plan instead of buckets	Slice to smallest reviewable decision-moving unit
Silent scope creep	Drift check: every add must trace to core decision
Marching bucket→bucket without pause	Checkpoint = hard stop for user review
Aspirational success signal	Rewrite as a tool-verifiable completion condition