toolu

Use BEFORE writing code or planning a build, feature, refactor, or behavior change whose shape is unsettled. Tells: "where do I even start", "this feels big", "help me scope it", "think through the approach and tradeoffs", "before I start coding". Skip mechanical work with no design decision and already-scoped features.

Use when the user asks to commit all current changes after running the repository's required quality gates.

Use when something is broken and you need the root cause — a failing or flaky test, a crash, a stack trace, wrong output, a regression, a Sentry issue. Drives a scientific-debug loop: reproduce → observe evidence → falsifiable hypothesis → instrument/bisect → isolate the ROOT cause (not the symptom) → fix → regression test → record. Tells: "why does X fail", "it crashes", "this is broken", "flaky test", "debug this", "root cause", "it worked before", "track down this bug", "stack trace". A non-chain break-glass loop in the toolu workflow — any phase can drop into it and return.

Use when the ask is deep research that must end in a multi-source cited report — tells: "deep research", "research report", "cited report", "survey the state of the art", "investigate thoroughly". Picks guiding questions, then fans out per-question researchers combining exa-search and context7. NOT for quick single-fact or API lookups — the research-agent subagent handles those internally — and NOT for local codebase questions (the deep-explore subagent). Standalone knowledge workflow — not part of the build chain.

Use when deciding HOW to run a large task: whether to delegate it at all, and if so how to split it. Teaches the MAIN thread that inline is the default and a subagent must earn its round trip — plus which agent for which job, how to bound a delegation so it cannot hang, how to parallelize genuinely independent work, and which model tier fits each class. Read it before fanning anything out, especially when tempted to split work that one thread could just do. Tells: "orchestrate this", "delegate this", "break this down", "coordinate subagents", "should I use subagents", "this is a big task", or a UserPromptSubmit nudge flagged the prompt as large.

Use after requirements are agreed when a behavior change needs an executable, ledger-backed implementation plan. Evidence-first and adaptive: mechanical work skips a plan; brainstorm is optional upstream triage.

Use to review the plan or poke holes in the plan before execution. Verifies ledger steps, AC coverage, real-input checks, paths, dependency order, docs, and PR-delivery readiness.

Use when completed branch work needs a final code review, fixes, full quality gates, and intentional local commits without pushing or merging.

Use when installing, previewing, updating, backing up, or removing toolu's custom Codex agent profiles.

Use to write the spec or document the design before planning a new system, cross-cutting feature, public interface, or other durable contract. Clear requirements may enter directly; brainstorm is optional upstream triage.

Use to review the spec or poke holes in this spec before planning or building. Validates authored contract sections, real-data acceptance evidence, scope, and blocking open questions.

Use while executing any feature, fix, refactor, or regression to design high-signal, real-data tests. Enforces test-first discipline and colocated layout; it is a reusable method, not a terminal workflow phase.