outcome-first-agent-loop

name	outcome-first-agent-loop
description	This skill should be used when the user needs outcome-first plan handoff: explain a plan/TLDR, design Outcome Validation, set a short Codex goal, work from a plan, run independent review, test real or controlled usage, verify whether work is done, or close out development without main-agent self-pass.

Outcome-First Agent Loop

In complex development work, plans, chat summaries, goals, test output, and review evidence easily drift apart. An agent may remember what to build, then later use green tests or self-review as a substitute for real validation. This skill is used after a plan exists to add an outcome-first handoff and closeout layer.

This skill is a general overlay. It is not bound to any specific planning, implementation, or review tool, and it does not replace writing plans, implementing code, code review, testing, or real validation.

It does four things:

1. Explain the plan direction: turn the full plan into a user-readable core explanation so humans can judge direction, boundaries, and tradeoffs.
2. Design validation standards: explain how independent subagents will validate the development result, get user confirmation, then write a self-contained Outcome Validation / Gate Matrix back into the plan for agents to execute.
3. Guide the development goal: set a short, accurate, independently executable Codex goal before development so later agents can work from the full plan, Outcome Validation, Gate Matrix, and evidence requirements even if they never reread this skill.
4. Block premature completion: at closeout or when the user asks whether work is done, require the main agent to prepare the current evidence package and dispatch independent subagents according to the Gate Matrix. Missing required gate attestation means blocked or incomplete.

Core roles:

• Humans do not need to read the entire long plan. They need a short, self-contained explanation to judge whether direction, boundaries, and validation match the real need.
• The main agent reads the full plan, produces the readable explanation, writes confirmed validation standards back into the plan, sets the short goal, implements, and prepares the current evidence package.
• The full plan and plan-level Outcome Validation are the execution standard. The Gate Matrix defines required gates, score items, subagent attestation, scoring/iteration, and completion authority. Chat explanations and goals are handoff layers.
• Final pass/fail authority must come from independent subagent attestations for required gates. The main agent may precheck, collect evidence, and repair gaps, but cannot use self-review, green tests, or summaries as completion proof.
• Memory, old transcripts, old scorecards, and old review packets are clues only. They are not completion proof unless mapped to the current plan and rerun when needed.

Stage Routing

Determine the user's current stage first. If unclear, read references/workflow-routing.md.

1. Plan Explanation

Use for "explain this plan", "TLDR", "what is this design", or "show me the direction".

• Read the full plan and the original user request. Do not rely on title or summary only.
• Return a short, user-readable direction explanation, not a full plan summary.
• Explain the desired outcome, core mechanism, requirement fit, explicit non-goals, key tradeoffs, and evidence the user should see when it works.
• Explain internal terms, abbreviations, private file names, and mechanism names by purpose. Do not use terminology as its own explanation.
• If the original request is unavailable, say the explanation is inferred from the full plan.
• Include the full plan path and state that the full plan remains the execution standard.

Detailed output guidance lives in references/plan-tldr-template.md.

2. Validation Standards

Use for "design validation", "how should we verify this", "reviewer checks", "subagent checks", or "write it into the plan".

• First produce a short validation brief for user confirmation. Write back to the plan only after confirmation.
• The brief answers: which gates independent subagents validate, who validates each gate, what evidence they inspect, the main score items, and what fails.
• Do not expand full requirement ranges, reviewer rosters, evidence lists, or scoring tables in the brief. Put those in plan-level Outcome Validation.
• Plan writeback must expand the same rules into a self-contained Gate Matrix: gates, independent verifiers, evidence, score items, scoring/iteration, subagent attestation, non-substitutes, failure conditions, scope, and completion authority must not change from the brief.
• Development tasks consider plan coverage, code review, real or controlled usage, and task-specific risk gates by default; add security, data, UI, CLI, performance, migration, documentation, or research-quality gates based on risk.

Detailed rules live in references/validation-contract.md; task mapping lives in references/task-specific-validation.md.

3. Development Goal

Use for "start development", "work from this plan", "implement according to the plan", or "set a goal".

• Read the full plan and written Outcome Validation first. If Outcome Validation is missing, return to stage 2.
• Create a short Codex goal in the task's own language. Do not copy the plan or use a fixed template.
• The goal must be self-contained enough for later agents to close out without rereading this skill.
• The goal must include: full plan as implementation basis, Outcome Validation / Gate Matrix as evidence and independent-review basis, all in-scope work, reproducible evidence, and independent subagent dispatch for required gates.
• The goal must include the minimum closeout protocol: prepare the current evidence package, dispatch independent subagents for required gates, ensure required score items satisfy the plan-local scoring protocol, summarize the Final Gate Ledger, and keep repairing/collecting evidence/dispatching review when any required gate attestation or required score item is missing.
• The goal must state completion authority: update_goal(status="complete") is allowed only after the current evidence package is complete, all required gates have in-scope passing subagent attestation, and no unresolved scope/evidence/completion conflict remains.
• Missing evidence, missing real or controlled usage, missing required gate attestation, scope conflict, or inability to validate independently means continue repairing/collecting evidence/dispatching review, or mark blocked/incomplete when progress is genuinely impossible.

Detailed goal rules live in references/validation-contract.md.

4. Development Closeout

Use for "validate this", "is it complete", "can we close out", "done", "complete", or when an agent is about to declare completion.

• Read the full plan, Outcome Validation / Gate Matrix, goal, current development result package, and current evidence package.
• The main agent prepares evidence and dispatches independent review. It does not act as final judge.
• Current evidence must cover plan coverage, tests/logs/screenshots/artifacts, real or controlled usage, task-specific risk evidence, old-evidence mapping, and subagent dispatch status.
• When subagent tools are available, dispatch according to the Gate Matrix and wait for attestations. Split executor and scorer whenever scoring is needed and practical.
• The main agent summarizes the Final Gate Ledger, but the ledger is an evidence index, not self-review.
• Output only three statuses: passed, failed and needs repair, or blocked and needs evidence or independent review.

The closeout gate lives in references/execution-done-gate.md; reviewer packets live in references/independent-review.md; scoring rules live in references/review-scoring.md.

Output Contract

• End every stage with one short Next step recommendation. Do not skip user confirmation, file writes, development, or review gates.
• Plan explanation returns only the short direction explanation, full plan path, and next step.
• Validation standards first return the short brief. Write back to the plan only after user confirmation.
• Development goal returns a short goal body and precondition gate status.
• Development closeout returns current status, Final Gate Ledger summary, evidence gaps, dispatched or required independent subagent attestations, blocked reason, or smallest repair package.

Hard Gates

• Do not treat main-agent self-review, green tests, summaries, memory, or old review packets as completion proof.
• Do not treat skill references as runtime prerequisites. Stage 2 plan writeback and stage 3 goal text must let later agents execute and close out without rereading this skill.
• Do not give independent subagents hidden reasoning, expected answers, the full chat log, or same-round reviewer opinions.
• Do not collapse required gates into one generic scorer unless the task is low-risk and one-dimensional and the Gate Matrix or evidence package explains why.
• Runnable, interactive, deliverable, or user/agent-facing work must have a real or controlled core-path usage record.
• If the plan requires real end-to-end validation, mocks, stubs, previews, in-memory samples, or unit tests are supplementary only.
• External actions such as email, publishing, payment, deletion, or production submissions default to mock, dry-run, sandbox, preview, or controlled samples.

Reference Routing

Do not read every reference at once. Select the minimum file for the current stage:

• references/workflow-routing.md: determine stage and gates.
• references/plan-tldr-template.md: explain plan direction.
• references/validation-contract.md: create validation briefs, write Outcome Validation, and generate short goals.
• references/gate-subagent-contract.md: define Gate Matrix, Subagent Attestation, Final Gate Ledger, and completion authority.
• references/task-specific-validation.md: map validation to task type.
• references/execution-done-gate.md: closeout and completion decisions.
• references/independent-review.md: build independent review packets.
• references/review-scoring.md: per-gate scoring, direct failure rules, and repair loops.