ouroboros-loops:analyze

Ouroboros: Analyze

Classify the raw observations from the research step into actionable findings. Do not re-scan the codebase — work from the research data.

Procedure

0. Superpowers Gate

Check .ouroboros/config.json for the useSuperpowers field:

• Read config.json and inspect useSuperpowers
• If useSuperpowers is false or absent → skip Superpowers entirely for this step; proceed to step 0b
• If useSuperpowers is true → check whether the superpowers:plan skill is available in the current session
  • If available: after classifying findings (step 2), invoke superpowers:plan with the findings summary as input. Then:
    1. Collect the plan output (ordered task list with file targets and rationale)
    2. Read current state.json
    3. Write back state.json with a new top-level execution_plan field:

       {
         "execution_plan": {
           "generated_at": "iteration-N",
           "ordered_tasks": ["<task 1>", "<task 2>", "..."]
         }
       }
       

    4. The fix and enhance steps SHOULD read state.json.execution_plan (if present) to determine task ordering and file targets, in preference to their own ad-hoc selection logic.
  • If NOT available: log [SUPERPOWERS UNAVAILABLE] plan skipped — plugin not loaded and continue without it

The superpowersSteps.analyze field in config.json specifies which Superpowers mode to use for this step (default: plan).

0b. Check Prior Iteration Context

Read .ouroboros/state.json and note any items already marked [RESOLVED] or [DEFERRED]. Do NOT re-report them as new findings. Treat [DEFERRED] entries the same as [RESOLVED] — they are not eligible for re-classification or re-addition as fresh findings. This aligns with the determine SKILL.md specification which marks stagnant items [DEFERRED] to prevent re-surfacing.

Read the latest .ouroboros/reports/iteration-N.md if it exists to understand what was already addressed.

1. Read Research Data

Read .ouroboros/research.md — this contains the raw observations gathered in the research step.

If the file does not exist (e.g., first run or research step was skipped), fall back to reading key source files directly.

2. Classify Findings

Apply judgment to the research observations and classify into three categories:

bugs — Clear bugs, error-prone code, incorrect logic

• Examples: missing null checks, wrong type handling, unhandled exceptions, off-by-one errors

quality_issues — Code quality problems

• Examples: duplicated code, excessive complexity, unclear names, unused variables, poor separation of concerns

enhancement_opportunities — Improvements that would add value

• Examples: missing utilities, improvable APIs, tests worth adding, documentation gaps

When classifying, apply the user's intensity setting (from config.json or handoff.md):

• conservative: only report unambiguous issues with clear evidence
• balanced: report clear issues and well-justified improvements
• aggressive: include speculative improvements and broader refactoring opportunities

2b. Parallelization Eligibility Check

After classifying findings, determine whether the upcoming fix and enhance steps can run in parallel. This is the analyze step's responsibility as defined in agents/ouroboros-agent.md — Parallelization Guide, Path A.

Procedure:

1. Collect the set of files targeted by fix candidates (bugs + quality_issues findings that name specific files).

2. Collect the set of files targeted by enhance candidates (enhancement_opportunities findings that name specific files).

3. Check for intersection:

   • If the two sets are disjoint (no shared files) → parallel_eligible: true
   • If they overlap (one or more shared files) → parallel_eligible: false
   • If either set is empty or no specific files can be identified → parallel_eligible: false (conservative default)

4. Write the result into state.json as a top-level field (step 3 will write findings; write parallel_eligible in the same write operation or immediately after):

{
  "parallel_eligible": true
}

Why this matters: If parallel_eligible is absent or false, the Ouroboros agent will always run fix then enhance sequentially. Only by setting true here can Path A (Agent Teams) or Path B (Bash run_in_background) parallelization be activated. See agents/ouroboros-agent.md §Parallelization Guide for the dispatch patterns and concurrency limits.

Note: Do not set parallel_eligible: true speculatively. If there is any ambiguity about file overlap, default to false.

3. Update state.json

Update (merge) the findings field in .ouroboros/state.json. Do NOT replace the entire file.

Merge strategy:

• Preserve all [RESOLVED] entries — never drop or overwrite them
• Preserve unresolved entries not contradicted by new evidence
• Append new findings not already present in any form
• No duplicates

{
  "findings": {
    "bugs": [
      "[RESOLVED] existing-resolved-bug-preserved",
      "new-bug-appended"
    ],
    "quality_issues": [
      "[RESOLVED] existing-resolved-quality-issue-preserved",
      "new-quality-issue-appended"
    ],
    "enhancement_opportunities": [
      "[RESOLVED] existing-resolved-enhancement-preserved",
      "new-enhancement-appended"
    ]
  }
}

4. Hand Off

After saving state.json, output a completion message. The agent (not this skill) is responsible for invoking ouroboros-loops:context-handoff next.