goals

Files (7)

• SKILL.md
• owns-defers.md
• config-md-authoring.md · references/
• goals-md-template.md · references/
• post-lock.md · references/
• setup.md · references/
• worked-example.md · references/

SKILL.md (first lines)

# Goals (QRSPI Step 1)

!cat skills/_shared/precondition-block.md

**Announce at start:** "I'm using the QRSPI Goals skill to capture what you want to build."

**If auto-mode is detected** (presence of `## Auto Mode Active` system-reminder), surface before the first interactive step: "This skill is collaborative — turn-by-turn dialogue produces better Goals quality than autonomous execution. Recommend exiting auto-mode (`Shift+Tab` to cycle modes). I'll proceed in either mode if you prefer." Do not force the user out; respect their choice.

## Overview

Capture purpose, environmental constraints (when known), and the per-goal problem frames that downstream skills work against. Runs as an interactive conversation in the main session, persisting each locked decision directly to `goals.md` on disk.

Goals is **problem-framed**, not solution-prescribing. Each goal states a problem, why it matters, and what is known. Solution candidates surface in "What we know so far" as **possibilities for Design to weigh** — NOT commitments.

**Prohibition.** Goals does NOT author file maps, phasing decisions, or detailed solution definitions; those are owned by downstream artifacts.

## Goals OWNS / Goals DEFERS

!cat skills/goals/owns-defers.md

## The Three Stages

Goals runs three stages per invocation. First-Run Setup and After Goals Are Locked live in dedicated reference files and are read on trigger; the Defining Goals stage (the user-facing dialogue) lives below in this file.

- **First-Run Setup** (run-once on entry). Artifact directory creation, next-phase-restart detection, config validation, pipeline mode selection, `config.md` HARD-GATE. **Trigger:** Read `references/setup.md` on entry to Goals, BEFORE the first user turn of dialogue.
- **Defining Goals** (the bulk of the skill — captured below). What to ask, how to engage, what to write per goal, incremental persistence to disk, final coverage review.
- **After Goals Are Locked**. Review Round, Human Gate, Terminal State / next-skill handoff. **Trigger:** Read `references/post-lock.md` AFTER all goals are locked on disk and the user has signaled the dialogue is complete.

# Defining Goals

This stage covers everything between First-Run Setup (`config.md` written) and After Goals Are Locked (all goals locked; entering review). All rules in this stage apply per-goal during the conversation.

## What to Ask

- **One question at a time** — don't overwhelm.
- **Prefer multiple choice** when possible — but only for goal-articulation questions (see Dialogue Conduct Rule 5).
- Focus on the users, their needs, and any environmental constraints that are already committed to.

Question coverage (order follows the conversation; phrasing is a guide — adapt the voice but keep the intent):

1. **Who is this for?** Name the users concretely — end users, internal teams, API consumers, admins, ops, any stakeholder this work serves. **Are there secondary or tertiary users we should also consider?** (e.g., the primary user is a customer, but admins configure their experience, support staff handle their escalations, ops maintain the system serving them.) Capture every user the work touches — those secondary and tertiary users become angles for the Rule 9 stakeholder probe and the Final Coverage Review.
2. **What do we know about what those users want, need, or struggle with today?** Capture as user-need statements — outcomes the user is trying to reach ("users need to [verb]") not features we'd build ("we should build [noun]"). Classic trap: "users need a dashboard" → they need to digest varied information in one place; the dashboard is one possible solution.
3. **For each need, why does the user have it?** Probe root motivation by asking "why" 1–3 times. Stop when the answer is a durable user outcome rather than a process complaint, or when further probing turns philosophical. Goal: surface the underlying job-to-be-done, not interrogate.
4. **Do we have any concrete evidence for those needs?** Direct user feedback, support tickets, analytics, observed behavior, prior incidents — or is the need inferred or assumed? Mark each need's evidence basis (observed / inferred / assumed) so Research knows where to dig and Design knows what's verified vs hypothesis.
5. **Does the user have a workaround today?** The current journey — even if painful — signals problem magnitude and surfaces assumptions to overturn.
6. **Has this need been attempted to be solved before, here or elsewhere, that we should know about?** Prior internal attempts to avoid repeating; competing or adjacent products worth studying for inspiration; specific patterns to avoid (and why). Feeds Research and Design.
7. **For each goal, does it feel like `known-fix` (risk — solution space bounded) or `exploratory` (uncertainty — success criteria emerge through investigation)?** Default `exploratory` when uncertain; flag the ambiguity. Exploratory goals are protected from cost-benefit reasoning that would defer them.
8. **Are there any constraints already committed to?** Tech stack, timeline, compatibility, performance, deployment — *only if known*. A greenfield project may have none yet; do not invent or pressure for constraints that haven't been decided.
9. **Is this a new project or building on existing work?**

Do NOT ask for per-goal acceptance criteria, file maps, phasing, or "what's out of scope" — those are owned by downstream artifacts.

## Dialogue Conduct

When working a goal with the user, follow these rules.

1. **Open with questions.** Surface your list of open questions for the goal in chat. Work through them with the user one decision at a time.

2. **One question at a time, with a recommended answer.** Each question carries your proposed answer; the user confirms, amends, or rejects.

3. **Ground first, ask second.** Before asking the user any question — your own or one the user has asked back — consult the codebase, then the web. When a question touches industry best practice or external patterns, search the web for cited evidence rather than speculating or punting back. Escalate to the user only when no source surfaces a defensible answer.

4. **When the user asks for your call, provide one — at Goals altitude.** Give a grounded recommendation (sources per Rule 3) with named tradeoffs. Do not deflect with more questions. If grounding leaves the call indeterminate, say so and name what additional evidence would resolve it. If the question is solution-approach (methodology, algorithm, scoring rubric, architecture, "how to compute X"), the recommendation is *capture candidates in "What we know so far" and defer to Design* — not a pick between A/B/C/D. See Rule 5.

5. **Altitude check before every question.** Before asking the user any question, classify it: is the answer a *goal-articulation* fact (what is the problem, who is affected, why does it matter, what is currently known) or a *solution-approach* decision (how to compute, how to measure, which methodology, which algorithm, which architecture, which scoring rubric)? Only goal-articulation questions belong in this dialogue. If a question is solution-approach, do NOT ask it — capture it as an open question Design will weigh, list any candidates the conversation has surfaced under "What we know so far," and move on. The dialogue's job is to surface the problem; Design's job is to choose how to solve it.

6. **Sharpen fuzzy language.** When the user uses imprecise vocabulary, propose the canonical term and ask for confirmation before moving on.

7. **Walk every goal-articulation branch of the decision tree.** For each goal, resolve open questions one-by-one. Do not move to the next goal until every branch surfaced is decided, explicitly deferred with a written reason, or split out as a separate goal. "Branch" here means a goal-articulation branch (whose problem is this, what signal tells us it's a problem, what's the blast radius, who is affected) — NOT a solution-approach branch (which methodology, algorithm, architecture, multi-actor flow). Solution-approach branches are closed per Rule 5: list candidates in "What we know so far" for Design to weigh; do NOT force a user pick.

8. **Lock decisions as they settle.** Write each decision into the goal block under `status: draft` as it is confirmed (see § Incremental Persistence below). Do not accumulate decisions in chat across multiple goals before persisting.

9. **Probe for unstated goals before declaring the set complete.** User-volunteered goals are a *starting set*, not the complete set. Before treating the goal list as final, drive 1–2 probing passes by widening the stakeholder lens. Walk **every** user named in Question 1 — primary, secondary, tertiary — as a separate angle: for each, what do they need that hasn't been captured yet? Add operators, security or compliance reviewers, downstream consumers, future maintainers, and support staff to the list if they weren't named already. Each may have a legitimate user-need (e.g., "an operator needs to roll back a release without data loss") that the primary-user focus missed. Useful probes: "What does success look like for [user X]?", "What would make this fail for [user Y] even if every stated goal lands?", "Is there anything [user Z] needs that we haven't named?" Capture any new stakeholder needs the user confirms as additional goals; then run the Final Coverage Review below.

## Final Coverage Review (before declaring goals locked)

After the user signals they're done articulating goals — and after the Rule 9 in-flow stakeholder probing — pause for a deliberate **set-level review** of the locked goals before handing off to After Goals Are Locked.

Read the on-disk draft as a whole, with each user named in Question 1 (primary, secondary, tertiary) and their stated needs / evidence / workarounds in mind. Ask: does this set tell a complete story for *every* named user? Are there obvious goals nobody has named — implied by the evidence, the workarounds, or the stakeholders mentioned — that would round out the picture?

The number of candidates is **zero to many**. Propose every reasonable gap you spot, batched in one turn so the user can weigh them together:

> "Looking at the set together against the named users, I see [N] potential gaps:
>
> 1. **[name]** — given [evidence anchor], a goal like `[one-line problem]` would cover [user X].
> 2. **[name]** — [evidence anchor] suggests `[one-line problem]` for [user Y].
> 3. … etc.
>
> For each: add, defer, or skip?"

**Don't be shy.** If a candidate is reasonable, propose it. The cost of one user veto is small; the cost of shipping a goal set with an obvious gap is real work in the next QRSPI cycle.

**Zero candidates is also fine.** If nothing jumped out, say so explicitly ("set looks coverage-complete to me — nothing else jumped out") and hand off. Do not invent candidates to fill the slot.

## Goal Specificity

**Rule:** Each goal must be independently scopeable — moveable between phases without surgery. Bundled goals must be split with their own IDs. **Red flag:** a goal whose **Problem** bundles 3+ distinct problems that could be independently phased. **Late splitting:** classify per amendment severity (Minor / Major / Scope Unknown) — see `replan/SKILL.md`. Present each split as a before/after diff; user decides; update `roadmap.md` with new IDs. **Common rationalization:** "These items are related so they should be one goal" — Related ≠ coupled.

## What to Write — Per-Goal Block

When a goal is locked, the block written to `goals.md` MUST conform to the conformance template at `skills/goals/references/goals-md-template.md` (read it the first time you author a per-goal block). The rules below are the load-bearing constraints; the template is the formatting reference.

!cat skills/_shared/evergreen-output-rule.md

**The three required subsections.** Every goal MUST carry exactly the three subsections `Problem`, `Why we care`, `What we know so far`. Omitting one is a defect. If the user did not articulate one during dialogue, re-enter dialogue to obtain it — do NOT write a placeholder, partial, or tentative body (presence ≡ locked, see Incremental Persistence below). Do NOT add a fourth subsection — additional content belongs in `What we know so far` or in a Constraint.

**The `type` field — concrete value.** Every goal MUST carry a `type` field with exactly one concrete value: `known-fix` OR `exploratory`. Grounded in **Knight risk-vs-uncertainty**:

- **`known-fix`** — *risk*. Well-characterized problem; bounded solution space. Cost-benefit reasoning applies normally.
- **`exploratory`** — *uncertainty*. The problem is partly uncharted; success criteria emerge through investigation. Exploratory goals are **protected from cost-benefit reasoning that would defer them**.

NEVER emit the alternation literal `known-fix | exploratory` (template placeholder, not valid output). If neither fits, default to `exploratory` and flag the ambiguity under "What we know so far". Do NOT invent a third value.

**Solutions-as-possibilities framing.** When the user mentions a candidate fix during dialogue, transcribe it under "What we know so far" with explicit framing ("candidate Design should weigh" / "possibility for Design to evaluate"). Do NOT promote it to Purpose, Constraints, or a `Solution` subsection.

**No `Out of Scope`, `Success Criteria`, or `Acceptance Criteria` section** — top-level or per-goal. What isn't a goal isn't in scope; acceptance is owned by Design's per-goal `Acceptance` blocks and Plan's per-task expectations. Capture user-volunteered exclusions as constraints (when they shape the solution space) or omit them.

## Incremental Persistence (Direct-to-Artifact Drafting)

From dfrysinger/qrspi-plus, MIT.

More from dfrysinger/qrspi-plus