drive-outcomes

Drive Outcomes

Merges outcome-definition (Stage 1) and implementation (Stage 2) into one continuous session with a checkpoint. This eliminates cold-start information loss between planning and implementation — the agent that validates criteria against real data is the same agent that implements production code.

Session A (define + explore) produces a forensic TASKS.md. The user reviews and may /clear or continue. Session B (implement on branch) reads that artifact, refactors exploratory snippets into production code, and commits.

Trigger

/drive-outcomes <plan-path>

Where <plan-path> is the path to PHASE_PLAN.md (the output of /init-project or /define-outcomes).

Pre-flight

The target project MUST have a CONTEXT.md (produced by /init-project). If none exists, prompt the user to run /init-project first and stop.

Command-line Tools

• use fd instead of find
• use rg instead of grep

Output

• notes/plans/<phase-slug>/DECISIONS.md — design decisions from the grill
• notes/plans/<phase-slug>/TASKS.md — forensic task breakdown with success criteria

Process

Session A: Define + Explore

Step 1: Setup

# Set stage marker and session start for metrics tracking
echo "drive-outcomes" > .claude/.current_stage
date +%s%3N > .claude/.session_start

# Determine phase slug from plan path
PHASE_SLUG=$(basename $(dirname <plan-path>))
mkdir -p notes/plans/$PHASE_SLUG

# Ensure pipeline state directory is gitignored
grep -qx '.claude/' .gitignore 2>/dev/null || echo '.claude/' >> .gitignore

Step 2: Load Context

Read the constitution, plan, deferred items, and failure patterns:

# Read the constitution
cat CONTEXT.md
cat CONTEXT-MAP.md 2>/dev/null || echo "NO_CONTEXT_MAP"
fd -e md . docs/adr/ 2>/dev/null | sort | while read f; do
  echo "=== $f ===" && cat "$f" && echo ""
done

# Read the plan
cat <plan-path>

# Read deferred improvements from prior phases
fd deferred.md notes/pr-reviews/ | while read f; do echo "=== $f ==="; cat "$f"; done

# Read failure patterns
cat notes/failure-patterns.md 2>/dev/null || echo "No failure patterns catalog yet"

# Read the ODD pattern reference
cat "${CLAUDE_PLUGIN_ROOT}/skills/drive-outcomes/references/odd-pattern.md"

Step 3: Grill — Goals, Criteria, and Ground Truth

Launch a grill-me subagent that interviews the user about:

1. Goals: What is this phase trying to achieve?
2. Fixture files: What real data files exist for the target functionality? Ask explicitly. If no fixtures exist, criteria must still cite concrete expected values from a spec or reference implementation.
3. Success criteria: For each goal, what would winning look like? What concrete values can be extracted from fixtures?
4. Architecture decisions: Crate boundaries, type choices, patterns — but focused on outcomes, not implementation tactics.
5. Domain language: Validate terms against CONTEXT.md. Update CONTEXT.md inline.

The agent references odd-pattern.md for placebo test detection and fixture anchoring protocol. It does NOT discuss implementation details (those are discovered in Steps 5-6).

Output: notes/plans/<slug>/DECISIONS.md with:

• Declared fixture paths (with descriptions)
• Success criteria (per-goal, concrete, source-cited)
• Architectural decisions
• Domain terms validated

Step 4: Explore — Validate Criteria Against Real Data

For each set of criteria declared in the grill:

1. If fixture files exist, write exploratory snippets that read them and assert against the declared criteria.
2. Run them. If they fail:
   • Criteria may be wrong (wrong expected value, wrong tolerance) — adjust and document why.
   • The format may be different from what the criteria assumed — update criteria.
3. If no fixture files exist, verify each criterion can produce a meaningful assertion. If criteria are too weak (e.g., "should parse successfully"), flag them and ask the user for concrete expected values.

This step is interactive — findings are reported to the user as they happen.

Step 5: Write Forensic TASKS.md

Write notes/plans/<slug>/TASKS.md following the forensic-tasks-spec.md format. This is the checkpoint artifact. It includes:

• Declared fixtures at the top level
• Success criteria per task (anchored, sourced, falsifiable, with verification granularity and counter-example/test-fixture scope)
• Test code that references real fixture files
• Exploration notes documenting what was learned, adjusted, or surprised
• Grouped tasks with dependency mapping
• ODD pattern reference path

Source-audit requirement (anti-speculation gate): For each task that cites a reference implementation source file (e.g., CASTEP ion_atom.f90:5641-5876), you MUST read the cited source lines BEFORE writing the task description. Base the algorithm description on what the code actually does — not on general domain knowledge or assumed algorithm structure. Document key findings inline in the task description:

• The actual algorithm — not what you guessed it would be
• Subroutine/function signature — inputs, outputs, side effects
• Call graph — what subroutines/ functions does it call?
• Control flow — branches, early returns, edge cases, loop structure
• Indexing conventions — Fortran 1-based, C 0-based, stride patterns
• Data sources — where do inputs come from at the call site?

If a task cites or implies a reference implementation but has no source citation, search the reference source tree to find and read the relevant code before writing the description. Do NOT write speculative algorithm descriptions under any circumstance.

Rationale (failure-patterns.md: 2026-05-16, pattern: source-citation-without-reading): Task descriptions written from general knowledge are routinely wrong — sometimes every line is wrong (3-point finite-difference log-grid vs. spherical Bessel + DSYGV). The source citation exists precisely to prevent this; treating it as decorative context undermines the entire pipeline.

Checkpoint Pause

Present the forensic TASKS.md to the user for review:

"Forensic TASKS.md written at notes/plans/{slug}/TASKS.md. {N} tasks in {M} groups.

Success criteria are anchored to:

• {N} fixture files declared
• {N} criteria with concrete expected values
• {N} criteria adjusted during exploration

Review the TASKS.md. When you're satisfied, reply 'continue' to proceed to implementation. You may also /clear and re-invoke with /drive-outcomes --resume.

Commit the checkpoint:

git add notes/plans/$PHASE_SLUG/
git add .gitignore
git commit -m "docs: add forensic TASKS.md for $(basename $PHASE_SLUG)"

Session B: Implement (same session or resumed)

If continuing in the same session, proceed to Step 6. If resumed after /clear:

# Restore state
echo "drive-outcomes" > .claude/.current_stage
PHASE_SLUG=$(basename $(dirname <tasks-path>))

# Read checkpoint
cat notes/plans/$PHASE_SLUG/TASKS.md
cat notes/plans/$PHASE_SLUG/DECISIONS.md

Step 6: Create Per-Group Branch

Determine the feature branch for this phase (creating it from main if needed), then create a per-group sub-branch for the task group:

FEATURE_BRANCH="feat/$(basename $PHASE_SLUG)"

# Ensure feature branch exists (no-op on resume)
if ! git show-ref --verify --quiet "refs/heads/$FEATURE_BRANCH"; then
  git checkout -b "$FEATURE_BRANCH" main
else
  git checkout "$FEATURE_BRANCH"
fi

# Create per-group sub-branch
git checkout -b "impl/$(basename $PHASE_SLUG)/<group-id>"

Step 7: Implement Tasks (edit→check→fix)

For each task in the group, dispatch to the implementation-executor subagent. Do NOT implement directly — delegate every task to the specialist agent.

Extract the task's section from TASKS.md (including its success criteria, files, changes, and acceptance commands). Pass it as the agent's instructions along with the project path and workflow flag:

Model discipline: The implementation-executor agent definition specifies model: haiku. Do NOT pass a model override in the Agent() call — not opus, not sonnet. The edit→check→fix loop is well-served by haiku. Passing opus wastes 10-50× cost for zero quality gain and violates the pipeline's resource discipline.

No re-speculation: The task description in the dispatch prompt must come verbatim from the source-audited TASKS.md written in Step 5. Do NOT add, rephrase, or extrapolate algorithm details from general knowledge at dispatch time. If the TASKS.md description feels underspecified, read the cited source yourself (following the Step 5 protocol) and include the actual source findings in the prompt — never invent.

Source citation carry-forward: If the task cites a reference source file (e.g., CASTEP ion_atom.f90:5641-5876), include the exact citation in the prompt AND instruct the subagent to read the cited lines before writing any code. The citation is a read instruction, not decoration.

kind: lib-tdd — dispatch with workflow: 'odd':

• description: the task description, success criteria, test code
• PROJECT_PATH: the project root
• workflow: 'odd'
• odd_pattern_path: path to odd-pattern.md reference
• The agent follows the ODD cycle (criteria→explore→implement→refactor→verify)
• Tests MUST use declared fixture files and assert against concrete values
• After VERIFY passes: agent commits with feat(<slug>): <task-id> (ODD): <desc>

kind: direct — dispatch with workflow: 'direct':

• description: the task changes and acceptance commands
• PROJECT_PATH: the project root
• workflow: 'direct'
• The agent applies changes, runs cargo check, fixes errors (up to 5 iterations)
• After cargo check passes: agent runs acceptance, then commits

Auto-review before commit (both kinds, done by the subagent):

1. Diff check — only files in scope
2. Intent check — matches guidance
3. Ground-truth check — no placebo assertions, fixtures used when declared
4. Acceptance check — commands pass
5. Conditional-guard parity check — for lib-tdd tasks involving algorithm porting from a reference: every if/when/case/early-return in the reference function must have a corresponding condition in our implementation or an explicit justification why it's not needed. Source both the reference line and the justification.

After the subagent returns, verify the commit was made. Then update the resume note:

# Resume: <slug>/<group-id>
**Tasks done**: TASK-1, TASK-2
**Next task**: TASK-3
**Status**: in-progress

Step 8: Workspace Validation

After all tasks in a group complete:

cd "${CLAUDE_PROJECT_DIR}" && cargo check --workspace 2>&1
cd "${CLAUDE_PROJECT_DIR}" && cargo clippy --workspace -- -D warnings 2>&1
cd "${CLAUDE_PROJECT_DIR}" && cargo test --workspace 2>&1 | tail -40

Step 9: Merge Sub-branch

FEATURE_BRANCH="feat/$(basename $PHASE_SLUG)"
git checkout "$FEATURE_BRANCH"
git merge --ff-only "impl/$(basename $PHASE_SLUG)/<group-id>"
git branch -d "impl/$(basename $PHASE_SLUG)/<group-id>"

Workspace validation again on the feature branch:

cd "${CLAUDE_PROJECT_DIR}" && cargo check --workspace 2>&1
cd "${CLAUDE_PROJECT_DIR}" && cargo clippy --workspace -- -D warnings 2>&1
cd "${CLAUDE_PROJECT_DIR}" && cargo test --workspace 2>&1 | tail -40

Clean up resume note:

rm -f "${CLAUDE_PROJECT_DIR}/.claude/resume-<slug>-<group-id>.md"

Step 10: Report

CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT}" CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR}" \
  uv run --directory "${CLAUDE_PLUGIN_ROOT}" python \
  "${CLAUDE_PLUGIN_ROOT}/scripts/eval-session-metrics.py" drive-outcomes

"Outcomes driven for phase "{Phase Name}".

{N} tasks implemented, criteria anchored to {M} fixture files. Exploration adjusted {K} criteria during validation.

Next step: /make-judgement notes/plans/{slug}/TASKS.md for cross-group review."

Boundaries

Will:

• Grill the user on goals and success criteria (not implementation tactics)
• Ask the user to declare fixture files explicitly
• Write exploratory snippets against real data before committing to criteria
• Produce forensic TASKS.md with anchored success criteria
• Audit cited source files before writing any task description — read the actual reference code, don't speculate
• Implement on branches with compiler feedback
• Auto-review for placebo tests before commit
• Leave a forensic record of what was learned and adjusted
• Re-verify factual claims from subagent summaries by reading cited sources directly before taking action on them
• Use the implementation-executor's default model (haiku) — never override

Will not:

• Write task descriptions from general knowledge when a source citation is available — read the cited source first
• Override the subagent model (opus/sonnet) when dispatching to implementation-executor
• Discuss implementation patterns or tactics during the grill (that's what exploration is for)
• Use exact before/after blocks — guidance is descriptive
• Skip fixture anchoring when fixtures exist
• Allow vacuous assertions in test code
• Treat source citations as decoration — they are read instructions