goals

Files (4)

• SKILL.md
• owns-defers.md
• goals-md-template.md · references/
• worked-example.md · references/

SKILL.md (first lines)

# Goals (QRSPI Step 1)

**PRECONDITION:** Invoke `qrspi:using-qrspi` skill to ensure global pipeline rules are in context. (Idempotent on session re-entry. Subagents are exempt — SUBAGENT-STOP in using-qrspi handles that.)

**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, and the per-goal problem frames that downstream skills work against. Runs as an interactive conversation in the main session, then launches a subagent to synthesize the artifact.

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

This section is the **single source of truth** for goals.md scope boundaries. It is the locked rule set the scope-reviewer dispatch loads at review time (Read by the `qrspi-goals-scope-reviewer` agent at runtime per its rules-loading procedure). Findings cite this list directly.

### Goals OWNS

- **Project purpose.** One- or two-sentence framing of what is being built and the problem space.
- **Environmental constraints.** Tech stack, compatibility, performance budgets, deployment, timeline — the real-world conditions any solution must respect.
- **Per-goal entries.** Each goal carries:
  - a stable **goal ID** (e.g. `G1`, `G2`, …) that downstream artifacts (questions, research, design, structure, plan, roadmap, future-*) reference,
  - a **`type` field** with allowed values `known-fix | exploratory` (see "Goal Type Field" below),
  - exactly three subsections — **Problem**, **Why we care**, **What we know so far** — and no others.
- **Optional `Cross-Cutting Notes` section.** Top-level only when relationships between goals genuinely cross-cut. Omit when not needed.
- **Solution candidates as possibilities.** Solution IDEAS may appear under "What we know so far" framed as candidates Design should weigh — never as commitments.

### Goals DEFERS

- **Out-of-scope decisions** → eliminated. What isn't a goal isn't in scope. Project-level scope clarifications (if any) belong to Design's Approach where solution scope is decided.
- **Detailed solution definitions** → Design.
- **Acceptance criteria** → Design's per-goal `Acceptance` blocks + Plan's per-task expectations. Goals does NOT enumerate per-goal acceptance criteria.
- **File / component / interface mapping** → Structure.
- **Task specs, LOC estimates, dependencies** → Plan.
- **Phasing decisions, vertical slice authoring, roadmap** → Phasing.
- **Implementation logic, function signatures, assertion text** → Structure / Plan / Implement.

### Permitted Incidental References

The DEFERS list is about *ownership* of decisions, not *mention* of the deferred surface. The following incidental references are PERMITTED and MUST NOT be flagged as boundary violations by the scope-reviewer:

- **User-locked decisions made during Goals dialogue.** When the user explicitly locks a direction during the Goals interactive dialogue, the artifact MAY record that lock under "What we know so far" using a provenance marker such as `Decision locked during this Goals dialogue:` or `User-locked during Goals dialogue:`. Provenance trumps the candidate-framing rule — the user is the authority, and recording the lock truthfully is more important than re-framing it as a candidate. The lock applies only to the goal's framing, not to Design's downstream decisions about how to implement it.
- **Acceptance candidates framed as candidates.** Sentences that surface possible acceptance approaches using candidate verbs (`could include`, `Design should weigh`, `candidate acceptance approach:`) are PERMITTED. Sentences that bind acceptance with imperative verbs (`Acceptance must include`, `Acceptance must measure`) are NOT — those still violate the rule.
- **Cross-goal sequencing intent in Cross-Cutting Notes.** Goals OWNS goal relationships; ordering hints between goals (e.g. "G8 lands last because trimming files G1-G7 edit creates merge churn") are part of expressing those relationships and are PERMITTED in `## Cross-Cutting Notes`. The actual phase boundaries and roadmap are still Phasing's call — Goals records the *coupling rationale*, not the phase decision.
- **One-sentence mechanism sketches in candidate-fix bullets.** A single sentence describing a candidate fix's mechanism (e.g. "validate actual merge-parent SHAs against named task-tip SHA set; halt on mismatch") is PERMITTED. Multi-line shell pseudocode with specific variable names, command flags, or assertion text is NOT — that level of specificity belongs to Structure / Plan / Implement.

The scope-reviewer evaluates the deferred surface against these carve-outs FIRST before flagging a boundary finding. A scope finding is only valid when the artifact crosses the boundary in a way the carve-outs do not permit.

## Goal Type Field

Every goal MUST carry a `type` field with 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** — value comes from learning that hasn't happened yet. Do NOT drop or down-rank because it "isn't shovel-ready" or "has unclear payoff."

If neither fits, default to `exploratory` and flag the ambiguity under "What we know so far". Do NOT invent a third value.

## Artifact Gating

**Required inputs:** None (this is the first step)

**Before starting:**
1. Create the artifact directory: `docs/qrspi/YYYY-MM-DD-{slug}/` (relative to the project root, not the plugin directory)
   - **Slug generation:** Take the user's first description of what they want to build, extract 2-4 key words, convert to lowercase kebab-case. Examples: "I want to add user authentication" → `user-auth`, "Build a search API for products" → `product-search-api`. If ambiguous, ask the user to confirm.
   - If the directory already exists, ask the user if they want to continue an existing run or start fresh
2. Mark the provisional "Goals" task (created by `using-qrspi`) as `in_progress`.

### Next-Phase Restart Mode

Goals runs in three contexts:

- **Fresh run** — no artifact directory, no `config.md`, no `goals.md`. Run the full Interactive Dialogue + Pipeline Mode Selection.
- **Mid-run resume** — artifact directory exists; `goals.md` may already be `approved`. Validate `config.md` and continue from where the user left off.
- **Next-phase restart (invoked by Replan's minor path)** — a prior phase completed. **Replan auto-populates the draft `goals.md` from `roadmap.md` + `future-goals.md`**: Replan reads `roadmap.md` for the next phase's goal IDs, extracts matching entries from `future-goals.md`, and writes them as the new draft `goals.md` (`status: draft`). `artifact_promote_next_phase` has reset goals/research/design frontmatter to `draft` and deleted phase-scoped files (`structure.md`, `plan.md`, `tasks/`). The `phases/phase-NN/` snapshot exists; `config.md` carries the original route and pipeline.

**Detecting next-phase restart:** all three hold:
- `phases/phase-*/` snapshot directory exists
- `goals.md` exists with `status: draft`
- `config.md` exists with valid `route` and `pipeline`

**Behavior on next-phase restart:**

0. **Fail-closed precondition.** STOP on any failure — do NOT silently dialogue against an empty/partial draft (silent goal loss is the failure mode this guards):
   1. `roadmap.md` exists in the artifact directory.
   2. `future-goals.md` exists.
   3. The auto-populated draft `goals.md` is non-empty and well-formed.
   4. The draft contains ≥1 goal whose ID matches an entry in `roadmap.md`'s next-phase row.

   On failure, surface a concrete diagnostic and ask the user how to proceed (re-run Replan, hand-fix, abort).
1. Skip artifact-directory creation.
2. Skip the Pipeline Mode Selection questions (the existing `config.md` carries `pipeline` and `route`). Still run Config Validation to catch hand-edits.
3. Run a focused Interactive Dialogue against the auto-populated draft: confirm promoted goals match the user's next-phase expectation; capture new constraints (the Replan feedback file `feedback/replan-phase-NN-round-MM.md` is one input).
4. Re-synthesize `goals.md` (subagent) with the auto-populated content + new constraints. Preserve goal IDs from `roadmap.md` so downstream references stay valid.
5. Run the standard Review Round + Human Gate; on approval, write `status: approved` and let the pipeline cascade.

<HARD-GATE>
Do NOT synthesize goals.md until the pipeline mode is selected and config.md is written.
The user must explicitly choose quick fix or full pipeline before synthesis begins.
</HARD-GATE>

### Config Validation (when config.md exists)

If `config.md` already exists (resuming a run), apply the **Config Validation Procedure** in `using-qrspi/SKILL.md`. Goals validates `route`, `pipeline`, `second_reviewer`, `verifier_enabled`, `scope_tagger_enabled`, `visual_fidelity_required`, and (when `pipeline: quick`) `question_budget`.

## Process

### Interactive Dialogue

- **One question at a time** — don't overwhelm
- **Prefer multiple choice** when possible
- Focus on purpose, constraints, the per-goal problem frames
- **Scope check:** If the request describes multiple independent subsystems, flag immediately. Help decompose into sub-projects — each gets its own QRSPI run.

Questions to cover (order follows the conversation):
1. **What are you building?** Core purpose / problem space.

From dfrysinger/qrspi-plus, MIT.

More from dfrysinger/qrspi-plus