/whats-next → /goal brief

Goal

Make the shipped /whats-next skill culminate in an action the user can run hands-off: after it presents its ranked recommendations and the user picks one, the skill emits a single, ready-to-paste goal brief (≤ 4000 characters) that the user runs as Claude Code's built-in /goal <brief> command. The brief is engineered so that the resulting autonomous, long-running session delivers a fully thought-out, tested, iterated, and verified solution — not a half-built MVP.

Background — how /goal actually works

Per the Claude Code hooks reference, /goal <text> is a built-in shortcut for a session-scoped, prompt-based Stop hook. The <text> becomes a standing completion condition: at the end of every turn, an LLM judge re-reads it and decides whether Claude is allowed to stop. Claude keeps working across turns until the condition is judged met.

This single fact drives the entire design:

• The brief is both the driver and the stop-judge's rubric. It must contain an objectively evaluable "done when…" condition. The documented #1 failure mode is a vague goal that causes the session to spin forever (or stop prematurely).
• Evidence over claims. Anthropic's guidance: give pass/fail verification (tests/checks) and require Claude to show evidence of success, not assert it. The Stop judge can then anchor on concrete signals (test output, a working run).
• Length. Hook I/O strings cap at 10,000 chars; we hold the brief to ≤ 4000 to keep it focused and keep the per-turn stop-judgment cheap and reliable.
• Claude can't self-invoke /goal (it's user input). So the skill's deliverable is a copy-paste block plus a one-line instruction to run it.

Architecture

The /whats-next engine logic lives in a single source-of-truth file, jacked/data/commands/whats-next.md, read by Claude at runtime. /jacked-setup generates per-repo standalone configs by embedding this engine body verbatim after a ## Repo Config block. Therefore the new behavior is added in one place (the engine) and propagates to every standalone config for free — no jacked-setup.md template change and no new per-repo config knob (the behavior is universal, and adapts at runtime to the repo's project type / test command / UI-ness).

A new Step 8: Forge the Goal Brief (on pick) is appended to the engine. It does not fire during the initial analysis turn; it fires when the user selects an option (or asks to turn one into a goal) in a follow-up turn — which is how the single-read skill file already governs the whole interaction.

flowchart TD
    A["/whats-next invoked"] --> B["Steps 1-6: orient, discover,
signals, rank, present options"]
    B --> C["Step 7: setup hint +
start-work paths (/goal, /jack-it-up)"]
    C --> D{"User picks an option
(or asks for a goal)"}
    D -->|yes| E["Step 8: Forge Goal Brief
from chosen option + repo discovery"]
    D -->|no / switches focus| B
    E --> F["Fill template, drop
irrelevant blocks, trim ≤4000"]
    F --> G["Emit paste-ready block +
'run: /goal <paste>' instruction"]
    G --> H["User runs /goal → autonomous
Stop-hook delivery loop"]
  

flowchart TD
    A["/whats-next invoked"] --> B["Steps 1-6: orient, discover, signals, rank, present options"]
    B --> C["Step 7: setup hint + start-work paths (/goal, /jack-it-up)"]
    C --> D{"User picks an option (or asks for a goal)"}
    D -->|yes| E["Step 8: Forge Goal Brief from chosen option + repo discovery"]
    D -->|no / switches focus| B
    E --> F["Fill template, drop irrelevant blocks, trim <=4000"]
    F --> G["Emit paste-ready block + 'run: /goal ' instruction"]
    G --> H["User runs /goal -> autonomous Stop-hook delivery loop"]
  

The Goal-Brief Template

Step 8 instructs Claude to fill this template from the chosen option and the facts already gathered in Steps 1–6 (key files, evidence/issue refs, project type, real test command). Bracketed […]-tagged lines are conditional — when one applies, the line is kept and the […] tag itself deleted (never emitted); when it doesn't, the whole line is dropped. The whole brief is trimmed to ≤ 4000 characters before emit (the skeleton is ~1,900 chars, so there is ample headroom; trimming touches Context/Approach prose first, never the Build/Verify/DONE core).

This is the as-built template after the two-wave DCR hardening pass (see Review outcomes):

Deliver: <one-line outcome — the chosen option, as a shippable result>.

Context: lives in <key files/paths>. <1-2 lines: what exists today, what's
missing or broken>. Refs: <identifiers + a short neutral paraphrase —
issue #s, file:line, doc sections>.

Build the complete feature — no MVP, no stubs, no TODO-for-later:
- <concrete deliverable 1>
- <concrete deliverable 2>
- <concrete deliverable 3>

Approach: plan before coding (for L/XL, write the plan down first). TDD
where it fits — failing test, then implement, then green. Match existing
patterns in <area>. Build cleanly: no silent failures, no swallowed
errors, no arbitrary data/scope caps; follow CLAUDE.md. Stay in scope:
work only on this task's feature branch, committing each green increment
so an interrupted run is resumable — no force-push, history rewrite, data
deletion, or untrusted install/network scripts. If a step looks destructive
or out of scope, stop and ask.

Verify — run each and show the output; ALL must pass before you stop:
- <repo's real test command> exits clean, with NEW tests covering the
  new behavior and its edge cases
- The outcome works when run for real — paste the proof: <a concrete
  command + its expected output, or the user flow you walked>
- [UI work only] Browser-QA via available browser tools (or /qa,/ux):
  target flows work, console error-free
- [security-sensitive only] /cso runs, reports no high/critical findings
- [if /dcr available] /dcr runs and reports a clean pass

DONE when: the test command and the real-run proof both pass in the
transcript, every applicable review gate reports clean, and the work is
committed on a feature branch. Do NOT stop while any item is unmet or
unproven — diagnose, fix, re-run. Never report success without the
supporting output.

Outside the fenced block, Step 8 carries Step 1's DATA-only rule into the forge: references are cited by identifier + neutral paraphrase (never verbatim title), and any directive-like text in a title/label/note is replaced with [text omitted] — so untrusted issue/task text cannot ride into the autonomous loop. Option 0 (Resume Active Checkpoint) is excluded from forging and routed to /checkpoint resume instead.

What each part buys, mapped to the research:

Design Decisions

File Structure

Tasks (outline)

Detailed, TDD-ordered steps are produced by the writing-plans skill next. High-level shape:

• Task 1 — Write failing content-presence tests for Step 8 (RED).
• Task 2 — Add Step 8 + the brief template to the engine; tweak intro/Step 7 (GREEN).
• Task 3 — README paragraph.
• Task 4 — Full suite green; manual smoke (build wheel, install, generate a brief, eyeball ≤4000 + DONE-condition quality).
• Task 5 — Version bump + hand to /release.

Testing Strategy

These are LLM instruction documents, not executable code — so tests are content-presence checks that guard the critical contract from accidental deletion, not assertions about runtime behavior (which only Claude enforces at runtime). As built, tests/unit/test_command_whats_next_goal.py has 17 tests (anchored on once-only strings, mutation-verified to redden on deletion) covering, among others:

• A ## Step 8 section dedicated to the goal brief exists.
• It states the ≤ 4000 character ceiling and a trim/self-check.
• It requires an objective completion condition (DONE when / "completion condition" language).
• It requires verification with evidence (tests + verify-by-running + "evidence not claims").
• It includes the conditional UX/browser-QA block and the security (/cso) block.
• It tells the user to run the result as /goal and presents a paste-ready block.
• It fires on pick (references selecting/choosing an option).

Plus a manual smoke check: build the wheel, jacked install, run /whats-next in a real repo, pick an option, and confirm the emitted brief is ≤ 4000 chars with a crisp DONE-condition and correctly-included/excluded conditional blocks.

Review outcomes

Two design forks were resolved with the user up front: emit on pick, and a hybrid verification gate that includes browser UX/QA when the work is UI-facing.

A two-wave recursive review (/dcr: Guardrails, Security, Logic & Edge Cases, UX & Flow, Testing, Simplicity/Maintainability + a pre-mortem analyst) then hardened the implementation. All findings were fixed and re-verified clean in Wave 2 (mutation-checked):

• Injection (CRITICAL): the verbatim-quoted-evidence channel could carry an adversarial issue/task title into the autonomous loop → Refs: now paraphrases + omits instruction-like text; Step 1 rule extended to all echoed content.
• Option 0 misroute (CRITICAL): Resume-Checkpoint was being forged into a cold brief → now excluded, routed to /checkpoint resume.
• Tool-less Stop-judge (CRITICAL): Verify items hinged on unprovable claims / tools the judge can't run → reframed as run-and-show-output; negatives moved to build-constraints.
• Test gap (CRITICAL): the Verify checklist wasn't actually guarded (anchor words recurred) → re-anchored on Verify-unique strings; mutation-confirmed it now reddens on deletion.
• Autonomous safety (MEDIUM): no destructive-action bound → scope guardrail + incremental-commit resumability added.
• Edge cases (MEDIUM): no-test-runner repos and non-code/docs options → fallback + recast guidance in the footer.
• UX (MEDIUM): two conflicting copy/paste recipes → single authoritative recipe after the block; internal "(Step 8)" label removed from user-facing copy (with a regression test).

No open questions remain blocking.

Generated with the jacked HTML artifact template.