Aristotle Pipeline

Agent definition: aristotle-deconstructor.md

The user wants first-principles reasoning applied to a problem, with automatic handoff to planning and implementation if the problem requires code changes.

This skill orchestrates: Aristotle -> Optimus -> Cyrus with user gates.

Execution modes

This skill supports two execution modes, determined by the caller:

• gated (default) — every stage transition requires explicit user approval. Used when invoked directly by the user ("Aristotle, ..." or /aristotle-deconstructor).
• autonomous — Aristotle still runs its Phase 0 framing check and then either the full 5-phase analysis (quality is non-negotiable) or a Phase 0 stop (see below), but gates auto-approve for Optimus and Cyrus transitions. The orchestrator logs each gate decision instead of blocking. Only PR creation gates on user approval. Used when invoked by ticket-swarm or ticket-pickup with execution_mode: autonomous.

In both modes Aristotle has two legal outcomes:

• Full analysis — Phase 0 passed, followed by Phases 1-5, the Aristotelian Move, and (when code work follows) an Implementation Handoff.
• Phase 0 stop — Aristotle judged first principles the wrong tool for the question and returned a short analogy-based answer instead of the five phases. There is no Move and no handoff. Step 2 handles this outcome explicitly; do not treat it as a truncated or failed run.

When swarm_mode: true is also passed (typically from ticket-swarm), forward swarm_mode, execution_mode and unbounded (if present) to all downstream skills (Optimus, Cyrus) so they know to report results back to the swarm orchestrator rather than presenting interactive menus.

Responsibility boundaries

Each agent has a strict lane. The orchestrator (you) enforces these at every handoff. If an agent's output bleeds into another agent's domain, strip the offending content before passing it downstream.

Handoff contracts

Each stage produces a defined output shape. Only this output crosses the boundary — everything else stays within the agent.

Both handoffs are written contracts the orchestrator (you) checks by hand. These stages are prose-orchestrated Agent tool calls, not saved workflow scripts, so nothing enforces the shape for you. Pass every item listed below and confirm each is present and non-empty before launching the downstream agent. If an item cannot be filled from the upstream output, treat the stage as deficient: send it back to the upstream agent; in autonomous mode do so once, and if the revision is still incomplete, halt and surface the gap (the same rule as optimus-planner's Handoff contract). Never fabricate it.

Why these stages are not saved workflows (conversion audit, 2026-08): in gated mode every inter-gate span here is a single agent call, and the autonomous-mode Aristotle -> Optimus -> Cyrus stretch has plan-dependent topology — Step 2 can halt on a no-code-changes verdict, and Step 4 picks sequential vs wave-parallel Cyrus from the plan's Section 12 — so no gate-free span has the fixed 2+-agent topology a workflow script requires. The handoff lists apply regardless of orchestration style.

Aristotle -> Optimus handoff

Pass:

• The Aristotelian Move — the single highest-leverage action (1-2 sentences)
• Irreducible truths — the first principles that survive Phase 2
• Assumptions stripped — the inherited assumptions the Assumption Autopsy removed from the framing, recorded so Optimus does not reintroduce them
• Constraints — hard constraints on the solution space, including any user modifications or constraints stated at the gate; the one item that may legitimately be empty, passed as "none" rather than omitted
• The Implementation Handoff section — Aristotle's summary of what needs to be built, written as a strategic brief (what and why, never how); the narrative companion to the Move

Strip before passing:

• The full Phase 1-4 analysis (user has already seen it; Optimus doesn't need it)
• Any file paths, class names, or implementation specifics Aristotle may have included (these are Optimus's job)

Optimus -> Cyrus handoff

Pass:

• The full execution plan — every section it carries (12 in full form; a short-form plan has 1, 3, 4, 4a, 6 and 10). Cyrus executes from Section 3 (Affected Areas), Section 4 (Execution Plan, with its YAML todo ids), Section 4a (Reuse & Consolidation), Section 6 (Testing Plan) and Section 10 (Risk Register); confirm each of those is present and non-empty
• The Aristotelian Move (if pipeline started from Aristotle) — so Cyrus understands the strategic why

Strip before passing:

• Optimus's internal reasoning or alternative approaches it considered
• Any code snippets Optimus may have included (Cyrus writes all code)

Step 1: Launch Aristotle

Extract the user's problem from their prompt (strip any "Aristotle" prefix, "/aristotle-deconstructor" prefix, or similar). Launch the aristotle-deconstructor agent via the Agent tool with the user's problem as the prompt.

Wait for Aristotle's response: either the full analysis (5 phases + Aristotelian Move) or a Phase 0 stop.

Override re-invocation. If the user rejects a Phase 0 stop and wants the full deconstruction anyway, launch Aristotle again with the original problem plus this line prepended: Override: the user has reviewed your Phase 0 "wrong tool" verdict and wants the full five-phase analysis regardless. The agent is memoryless, so the override must be in the prompt — it cannot remember a prior verdict.

Subagent failure handling: Follow CLAUDE.md error handling defaults. If a subagent fails or times out, surface the failure and stop — do not present partial strategic analysis.

Validate output before presenting: If Aristotle's response contains code blocks, file paths, or implementation specifics anywhere other than its Implementation Handoff section (a Phase 0 stop has no such section, so on a stop any of these is a violation), note this to the user as a boundary violation and present only the strategic analysis.

Step 2: Present analysis and gate

Show the user Aristotle's complete output.

Phase 0 stop (either mode): If the response ended at Phase 0 with a "wrong tool" verdict — no Phase 1-5 sections, no Aristotelian Move — do not present the menu below; three of its four options assume a Move exists.

• Gated: present the short answer and ask:

  Aristotle judged first principles the wrong tool here and answered by analogy.
  
    -> o = Override — run the full five-phase deconstruction anyway
    -> x = Done

  On o, re-invoke per the override rule in Step 1 and return to Step 2.

• Autonomous: do not proceed to Optimus. Return an advisory outcome to the caller: outcome: advisory, a one-line verdict (the Phase 0 "wrong tool" ruling), and the analogy answer as the body. ticket-pickup emits pipeline_complete with outcome: advisory and comments the verdict on the ticket; ticket-swarm counts it under Advisory, not Blocked, and never retries or runs failure analysis on it. The same outcome shape is used when a full analysis concludes no code changes are needed (see Gate rules).

In gated mode (full analysis): Ask:

Aristotle has identified the highest-leverage path. What next?

  -> p = Proceed to Optimus for a detailed execution plan
  -> d = Drill deeper into a specific phase
  -> s = Stress-test the Aristotelian Move against objections
  -> x = Stop here (no code changes needed)

Wait for user input. Do not proceed without explicit approval.

In autonomous mode: Log the analysis summary and auto-proceed to Step 3 (Optimus). If the Aristotelian Move explicitly states no code changes are needed, halt and report back to the caller instead.

Step 3: Launch Optimus (if approved)

If the user chooses "p" or says to proceed:

Launch the optimus-planner agent via the Agent tool. Pass it only the handoff contract output (see Handoff contracts):

• The Aristotelian Move
• The irreducible truths
• The assumptions removed from the framing
• Constraints — fold in any additional context or constraints the user provided at the gate ("none" if there are none)
• The Implementation Handoff section (narrative companion to the Move)

Check each item is present and non-empty before launching — this is a written contract, not an agent()-enforced one.

Instruct Optimus explicitly: "This strategic direction comes from Aristotle's first-principles analysis. Do not re-litigate the strategy — your job is to make it executable."

Wait for the full execution plan.

Questions-only reply. Optimus may return clarifying questions instead of a plan (no plan sections, no sentinel). Like a Phase 0 stop, this is a legal outcome, not a truncated or failed run. In gated mode, relay the questions verbatim, collect the user's answers, and launch Optimus again with the same handoff plus the answers. In autonomous mode, do not guess and do not launch Cyrus; surface the questions to the caller (in swarm mode, record the ticket as blocked with the questions as the reason).

Validate output before presenting: If Optimus's response contains code implementations (beyond illustrative pseudocode in plan steps), note this to the user as a boundary violation.

Step 4: Present plan and gate

Show the user Optimus's complete plan.

In gated mode: Ask:

Optimus has produced the execution plan. What next?

  -> i  = Hand to Cyrus for TDD implementation (sequential)
  -> ip = Hand to Cyrus for parallel TDD implementation (wave-based)
  -> r  = Revise the plan (tell me what to change)
  -> x  = Stop here (plan only, no implementation)

If Section 12 of the plan says "Sequential execution recommended," note this to the user next to the ip option and suggest i instead.

Wait for user input.

In autonomous mode: Log the plan summary and auto-proceed to Step 5 (Cyrus). Use sequential execution (i) unless Section 12 explicitly provides a wave table with parallelizable steps, in which case use parallel (ip).

Step 5: Launch Cyrus (if approved)

If the user chooses "i" (sequential):

Launch the cyrus-tdd-engineer agent via the Agent tool. Pass it only the handoff contract output (see Handoff contracts):

• Optimus's full execution plan (every section it carries; 12 in full form)
• The Aristotelian Move (strategic context)
• Any user modifications or constraints mentioned during the gates
• Execution mode: sequential

Check that plan Sections 3 (Affected Areas), 4 (Execution Plan, with its YAML todo ids), 4a (Reuse & Consolidation), 6 (Testing Plan) and 10 (Risk Register) are present and non-empty before launching — this is a written contract, not an agent()-enforced one.

Instruct Cyrus explicitly: "This plan comes from Optimus. Execute it step-by-step with TDD discipline. Do not redesign the architecture or re-sequence the steps — if you hit a blocker, surface it rather than working around it."

If the user chooses "ip" (parallel):

Invoke the Cyrus skill's parallel execution mode. Pass:

• Optimus's full execution plan (every section it carries; 12 in full form), checked the same way as the sequential path (see Handoff contracts)
• The Aristotelian Move (strategic context)
• Any user modifications or constraints mentioned during the gates
• Execution mode: parallel
• Section 12 wave table as the scheduling input

The Cyrus skill will fan out one agent per step per wave, report between waves, and aggregate final results.

Gate rules

• In gated mode: never skip gates. Each stage transition requires explicit user approval.
• In autonomous mode: gates auto-approve. The orchestrator logs each decision and proceeds. Only PR creation (handled downstream by /pr-create-from-commits) gates on user approval. If Aristotle's analysis concludes no code changes are needed, or ends in a Phase 0 stop, do not launch Optimus: return an advisory outcome to the caller (outcome: advisory, one-line verdict, the analysis as the body). The callers treat advisory as a success distinct from blocked.
• Aristotle-only is valid. Strategic questions may not need code.
• Optimus can be skipped. If Aristotle identifies a trivial, fully-specified change (single function rename, one-line config), offer to skip straight to Cyrus — but only if the what, where, and how are all unambiguous.
• Each agent runs as a subagent to keep the main context clean.
• Enforce boundaries at every handoff. You are the orchestrator — if an agent strays outside its lane, filter its output before passing downstream.
• If the user says "drill deeper" or "stress-test" (gated mode only), send follow-up prompts to the Aristotle agent (or launch a new one with that context).
• Forward swarm flags. When swarm_mode, execution_mode, or unbounded are present, pass them through to every downstream skill invocation.

Truncation handling

When this skill invokes Aristotle, Optimus, or Cyrus via the Agent tool, the orchestrator must verify the returned response contains the <<task-complete>> sentinel before consuming its output. See ~/.claude/_shared/agent-turn-cap-warning.md for the detection rule, continuation budget, halt/skip behavior, and the agent_truncated metric to emit. Aristotle-truncation is especially load-bearing here — a truncated Implementation Handoff section silently corrupts Optimus's brief. A missing handoff is not by itself the truncation signature: a Phase 0 stop legitimately has no handoff and no Phases 1-5. The sentinel is the test — a Phase 0 stop that ends with <<task-complete>> is complete; a five-phase analysis that stops mid-handoff without the sentinel is truncated. A clarifying-questions reply from Optimus is neither: see Step 3.

Maintenance

If you discover something during this task that would improve this skill, propose the change and ask me to confirm before saving it.