olliecrow/high-confidence-changes

high-confidence-changes

Multi-agent collaboration

• Default to using subagents when they are likely to improve speed, quality, confidence, or keep the main context clean.
• Use subagents to widen coverage, dig deeper on one thread, get a fresh second opinion, or keep the main thread clean while side work runs.
• Split work into clear packets with owners, inputs, acceptance checks, and a synthesis step when parallelizing.
• Keep the main agent focused on synthesis, unblockers, and the next critical-path step; let subagents handle bounded side work that can run in parallel.
• Use single-agent execution only when scope is small or coordination overhead outweighs gains.

Proactive autonomy and knowledge compounding

• Be proactive: immediately take the next highest-value in-scope action when it is clear.
• Default to autonomous execution: do not pause for confirmation between normal in-scope steps.
• Request user input only when absolutely necessary: ambiguous requirements, material risk tradeoffs, missing required data/access, or destructive/irreversible actions outside policy.
• If blocked by command/tool/env failures, attempt high-confidence fallbacks autonomously before escalating (for example rg -> find/grep, python -> python3, alternate repo-native scripts).
• When the workflow uses plan/, ensure required plan directories exist before reading/writing them (create when edits are allowed; otherwise use an in-memory fallback and call it out).
• Treat transient external failures (network/SSH/remote APIs/timeouts) as retryable by default: run bounded retries with backoff and capture failure evidence before concluding blocked.
• On repeated invocations for the same objective, resume from prior findings/artifacts and prioritize net-new progress over rerunning identical work unless verification requires reruns.
• Drive work to complete outcomes with verification, not partial handoffs.
• Treat iterative execution as the default for non-trivial work; run adaptive loop passes. Example loop: investigate -> confidence gate -> plan -> implement -> verify -> battletest -> organise-docs -> git-commit -> re-review.
• Keep looping until actual completion criteria are met: no actionable in-scope next step remains, verification is green, and confidence is high.
• Run organise-docs frequently during execution to capture durable decisions and learnings, not only at the end.
• Create small checkpoint commits frequently with git-commit when changes are commit-eligible, checks are green, and repo policy permits commits.
• Never squash commits; always use merge commits when integrating branches.
• Prefer simplification over added complexity: aggressively remove bloat, redundancy, and over-engineering while preserving correctness.
• When you touch code, leave the touched area in a better state than you found it: clearer, simpler, tidier, and at least as performant unless the task requires an explicit trade-off.
• Before finishing any non-trivial task or pass, run at least one explicit consolidation pass across the touched code, docs, notes, tests, and configs.
• Use that pass to merge toward one clear source of truth, remove stale or duplicate material, and resolve contradictions before you declare the work complete.
• Do this by default as part of normal completion, even when the user did not explicitly ask for cleanup, consolidation, or contradiction resolution.
• Use simple, plain English in user messages, docs, notes, reports, code comments, and other explanatory writing. Avoid jargon, fancy wording, and complex phrasing. When a technical term is needed for correctness, explain it in simple words the first time. Default to short user-facing responses. Think about what the user most wants to know, and lead with that. Do not dump every detail by default. Always include important changes, blockers, verification gaps, and any important assumptions, nuances, principles, or decisions that shaped the work. Add more detail only when the user asks for it or when uncertainty or risk makes it necessary.
• Compound knowledge continuously: keep docs/ accurate and up to date, and promote durable learnings and decisions from work into docs.

Long-task checkpoint cadence

• For any non-trivial task (including long efforts), run recurring checkpoint cycles instead of waiting for a single end-of-task wrap-up.
• At each meaningful milestone with commit-eligible changes, and at least once per major phase, invoke git-commit to create a small logical checkpoint commit once relevant checks are green and repo policy permits commits.
• At the same cadence, invoke organise-docs whenever durable learnings/decisions appear, and prune stale plan/ scratch artifacts.
• If either checkpoint is blocked (for example failing checks or low-confidence documentation), resolve or record the blocker immediately and retry before expanding scope.

Terminal state contract (must follow)

The skill is complete only when all of the following are true:

• Objective completion: the user-requested outcome is achieved, or explicitly marked blocked with concrete blocker evidence.
• Decision completion: every material decision is explicitly resolved as very-high-confidence, high-confidence, medium-confidence, low-confidence, or not-applicable, with brief evidence.
• Step-level terminal completion: each numbered workflow step and each delegated subtask is explicitly resolved as done, blocked, or not-applicable, with brief evidence before advancing.
• Action completion: every high-confidence or very-high-confidence action in scope is executed end-to-end, or explicitly marked blocked with evidence.
• Deferral completion: every unresolved medium-confidence or low-confidence item is either investigated further until confidence improves or deferred to the user with the exact blocker.
• Verification completion: required checks, validation, and battle tests are executed for every implemented change, or any unavailable checks are explicitly called out with impact.
• Loop completion: no actionable in-scope high-confidence next step remains under the current objective.

Stop only after this terminal contract is satisfied; otherwise continue iterating.

Terminal state examples (adapt to skill)

• done: all material decisions are confidence-rated, all high-confidence actions are completed and verified, and all sub-high-confidence items are explicitly deferred or closed.
• blocked: progress cannot continue after bounded retries because required confidence cannot be established or a dependency/access issue prevents verification; blocker evidence and exact unblock action are reported.
• not-applicable: a possible change path is explicitly ruled out because high-confidence review showed no change is warranted.

Overview

Use this skill when the user wants Codex to act only on changes that are justified with high confidence. The skill is not "make more changes"; it is "make only the right changes when confidence is strong enough, and otherwise keep investigating or defer."

This includes the possibility that the highest-confidence outcome is to make no change at all. Treat a confident no-op as a valid successful result, not as an incomplete attempt.

Prefer empirical investigation, real data, real runs, and realistic user-perspective battle testing whenever feasible. Avoid mock or stub data unless there is no practical alternative; if you must use non-real data, explain why and what risk it introduces.

Confidence rubric (must follow)

Before acting on any material decision, evaluate all of these gates:

1. Requirement clarity: the request, constraints, and success criteria are clear enough to act without guessing.
2. Current-state evidence: the current behavior/problem/opportunity has been directly observed in code, docs, logs, tests, outputs, or reproducible probes.
3. Correct lever: the proposed action is the direct, simplest lever for the observed issue or improvement, not a speculative side quest.
4. Scope containment: the likely blast radius, invariants, and adjacent risks are understood well enough to keep the change surgical.
5. Verification path: there is a concrete plan to verify, validate, and battle-test the result with meaningful checks.
6. Operational readiness: required tools, data, permissions, and environment conditions exist to carry the action through to completion.

Assign confidence using this rubric:

• very-high-confidence: all six gates pass strongly, evidence is direct, contradictions are absent or resolved, and the verification path is concrete.
• high-confidence: all six gates pass, with only minor non-material uncertainty remaining.
• medium-confidence: one or more gates are only partially satisfied, evidence is indirect/conflicting, or material uncertainty remains.
• low-confidence: multiple gates fail, the change is speculative, or the consequences of being wrong are not understood.

Action rule:

• Act only on high-confidence or very-high-confidence decisions.
• Do not implement medium-confidence or low-confidence decisions.
• If confidence is below high-confidence, investigate further first.
• If further investigation still does not raise confidence to high-confidence, stop and defer that decision to the user.

Behavioral guardrails (must follow)

• Proceed without permission for standard in-scope steps (read/scan/summarize/plan/tests/edits/analysis). Ask clarifying questions only when requirements are ambiguous, missing inputs, or a risky decision cannot be inferred. Require explicit approval only for destructive/irreversible actions, executing untrusted code or installers, remote-state changes (push/deploy/publish), or changes outside the repo environment.
• Run a preflight before substantial work: confirm the expected cwd, verify required tools with command -v, and verify referenced files/directories exist before reading or searching them.
• State assumptions explicitly and try to resolve them with evidence before acting.
• Prefer no change over a weakly justified change.
• Prefer the simplest change that closes the gap with high confidence.
• Keep changes surgical and within scope; do not bundle speculative cleanups or opportunistic refactors, but do leave touched code clearer, simpler, and tidier when that improvement is obvious and high-confidence.
• Define success criteria before implementation and verify against them after implementation.
• Battle-test from the user perspective, not only from the internal implementation perspective.
• Prefer quoted paths and explicit path checks when running shell commands to reduce avoidable glob/path failures.
• If an environment variable is required, check whether it is already set before asking for it or stating it is missing.
• If there is nothing left to do, say so explicitly and stop.

Decision framing

When a decision is required, always provide:

• Background context sufficient to make the decision.
• The concrete evidence supporting the current confidence level.
• Pros and cons for each viable option.
• Your recommendation and the reasoning behind it.

If no decision is required, say so explicitly and continue.

Rationale capture

When you make or reject a change, capture the "why" in a durable place (code comments, docs, ADR, or tests) when the reasoning is non-obvious. Do not rely only on plan/ scratch notes. In your report, mention where the rationale was recorded.

Plan/docs/decisions robustness

• Treat plan/ as short-term scratch and never commit it.
• If plan/ is missing, create it (and any needed subdirs) only when edits are permitted; otherwise keep a lightweight in-memory log and state in the report that plan logging was not persisted.
• Treat docs/ as long-lived, evergreen guidance; prefer updating existing docs when they have a clear home, but create new focused docs/subdirectories when it improves navigability (and link them from related docs or indexes).
• If docs/decisions.md is missing, prefer using the setup skill to create it when allowed. If you cannot create docs, capture rationale in the smallest durable local place (code comments or tests) and call out the missing decision doc in the report.

Trigger phrases

Use this skill when the user asks for:

• high confidence changes
• only make high-confidence changes
• investigate until confident, then act
• do it only if confidence is high
• keep going until you are highly confident
• make the changes you are very confident about

Prompt templates

Use these copy-paste templates:

• [$high-confidence-changes] investigate deeply, act only on high-confidence decisions, and defer anything below high confidence.
• [$high-confidence-changes] treat no-change as a valid outcome, but fully execute and verify any high-confidence change end-to-end.
• [$high-confidence-changes] build confidence with real evidence, then plan, implement, verify, validate, and battle-test any high-confidence action.

Workflow

1. Preflight and framing:

   • Confirm the cwd, available tools, relevant paths, and execution constraints.
   • Restate the objective, invariants, and what would count as success.
   • Create a lightweight decision log in plan/current/ when useful; keep it untracked.

2. Build the decision register:

   • Enumerate every material decision in scope, including the decision to make no change.
   • For each item, record the current confidence level, known evidence, unknowns, and the next probe needed.
   • Separate reversible, low-blast-radius items from riskier ones, but still require the same confidence gate.

3. Investigate until confidence is earned:

   • Read code, docs, tests, logs, prior notes, and relevant history.
   • Run focused probes, experiments, or reproductions to establish current-state evidence.
   • Use real data and real workflows where practical.
   • Keep going until each material decision is either high-confidence/very-high-confidence or clearly blocked below that threshold.
   • If the best-supported conclusion is that no change should be made, mark that decision high-confidence and stop work on that branch.

4. Act only on high-confidence decisions:

   • For each high-confidence or very-high-confidence decision, make the smallest correct plan and execute it fully.
   • Carry the work through implementation, execution, cleanup, and local rationale capture.
   • A high-confidence change is not complete until an explicit consolidation pass confirms the touched area now has one clear source of truth.
   • For non-trivial work, prefer explicit plan -> implement -> verify -> battletest sequencing instead of ad-hoc edits.

5. Verify, validate, and battle-test:

   • Run the smallest meaningful checks first, then expand coverage.
   • Use realistic inputs, production-like configurations, and user-perspective paths when feasible.
   • After fixes, rerun the relevant checks before broadening out.
   • If verification reduces confidence below high-confidence, treat that as an active signal to re-open investigation rather than forcing the change through.

6. Close the loop:

   • Re-scan the objective for any remaining in-scope high-confidence actions and execute them.
   • Do not leave obvious next high-confidence steps undone.
   • Defer only the decisions that remain below high-confidence after reasonable investigation.

7. Report:

   • Use the shortest report that still resolves the outcome clearly.
   • Lead with what changed, what did not change, and whether the result is a confident no-op, a verified change set, or a blocked outcome.
   • Include only material decisions, confidence levels, and verification evidence.
   • Call out deferred medium-confidence and low-confidence decisions with the exact missing evidence or blocking tradeoff.
   • Always keep important changes, blockers, verification gaps, and important assumptions, nuances, principles, or decisions that shaped the work.

Skill composition

When this skill is triggered, compose other skills as needed:

• Use investigate to build confidence when the current state is unclear.
• Use plan when substantial work needs an execution-ready spec.
• Use execute to carry an approved high-confidence plan through completion.
• Use verify for targeted correctness checks.
• Use battletest for broader user-perspective and edge-case validation.
• Use organise-docs and git-commit at meaningful milestones.

If there is a conflict, the confidence gate in this skill wins: do not act on sub-high-confidence decisions just because another skill would normally continue.