investigation-cycle

name: investigation-cycle type: lifecycle description: HAIOS Investigation Cycle for structured research and discovery. Use when starting or resuming an investigation. Guides EXPLORE->HYPOTHESIZE->VALIDATE->CONCLUDE workflow with phase-specific tooling. recipes:

• inv generated: 2025-12-22 last_updated: '2026-02-01T21:21:47'

Investigation Cycle

This skill defines the EXPLORE-HYPOTHESIZE-VALIDATE-CONCLUDE cycle for structured investigation of research questions. It composes existing primitives (Skills, Commands, Memory) into a coherent research workflow.

When to Use

SHOULD invoke this skill when:

• Starting a new investigation
• Resuming work on an in-progress investigation
• Unsure of next step in research workflow

Invocation: Skill(skill="investigation-cycle")

The Cycle

EXPLORE --> HYPOTHESIZE --> VALIDATE --> CONCLUDE --> CHAIN
    |            |             |            |           |
    |            |             |            |     [route next]
    |            |             |            |           |
  evidence    synthesize     verdicts    spawns   /-------------\
  gathering   hypotheses    per hypo    + memory  |             |
                                                type=inv    has plan?
                                                  |            |
                                            investigation  implement
                                               -cycle       -cycle

E2.4 EXPLORE-FIRST Pattern:

Parallel to Implementation Cycle:

1. EXPLORE Phase

On Entry:

mcp__haios-operations__cycle_set(cycle="investigation-cycle", phase="EXPLORE", work_id="{work_id}")

Goal: Gather evidence through unrestricted exploration before forming hypotheses.

Actions:

1. Read work file: docs/work/active/{backlog_id}/WORK.md
2. MUST read ALL @ referenced files at document top before proceeding
3. MUST Glob referenced directories to find all files (e.g., @docs/work/active/INV-052/ → Glob("docs/work/active/INV-052/**/*.md"))
4. Query memory for prior related work: memory_search_with_experience
5. Explore freely: Read files, search codebase, fetch web content
6. Document evidence as discovered (no rigid format required)

Governed Activities (EXPLORE state):

• file-read: allow
• content-search: allow
• file-search: allow
• web-fetch: allow
• web-search: allow
• memory-search: allow
• file-write: warn (prefer notes over artifacts)

Key Insight (Session 262, WORK-036): Unrestricted exploration produces deeper analysis than constrained subagent invocation. Main agent explores freely; investigation-agent invocation is OPTIONAL.

Exit Criteria:

• Work file read with complete context
• MUST: All @ referenced files read
• Memory queried for prior related work
• Evidence documented (free-form notes acceptable)
• Sources examined are logged

Tools: Read, Glob, Grep, WebSearch, WebFetch, memory_search_with_experience

2. HYPOTHESIZE Phase

On Entry:

mcp__haios-operations__cycle_set(cycle="investigation-cycle", phase="HYPOTHESIZE", work_id="{work_id}")

Goal: Form hypotheses FROM the gathered evidence.

Actions:

1. Review evidence collected in EXPLORE phase
2. Synthesize 2-4 hypotheses that explain or address the objective
3. MUST cite evidence for each hypothesis
4. Define test method for each hypothesis (how will VALIDATE phase verify it?)
5. Define scope (In Scope / Out of Scope)

Governed Activities (DESIGN state):

• file-read: allow
• file-write: allow
• file-edit: allow
• memory-search: allow
• web-fetch: blocked (no new research - use EXPLORE evidence)
• web-search: blocked (no new research)

Key Insight: Hypotheses form AFTER exploration, not before. This is the inversion from the old HYPOTHESIZE-first pattern.

Exit Criteria:

• Hypotheses table populated with 2-4 hypotheses
• Each hypothesis has evidence citations
• Each hypothesis has defined test method
• Scope defined (in/out)
• Confidence level assigned to each hypothesis

Tools: Read, Edit, Write

3. VALIDATE Phase

On Entry:

mcp__haios-operations__cycle_set(cycle="investigation-cycle", phase="VALIDATE", work_id="{work_id}")

Goal: Test each hypothesis against the gathered evidence.

Actions:

1. For each hypothesis, review supporting/refuting evidence
2. Render verdict: Confirmed / Refuted / Inconclusive
3. Assign confidence level to each verdict
4. MUST cite specific evidence for each verdict
5. Document any unexpected findings

Governed Activities (CHECK state):

• file-read: allow
• content-search: allow
• memory-search: allow
• shell-execute: allow (for verification commands)
• file-write: warn (verdicts only)
• web-fetch: blocked (no new research)

Key Insight: VALIDATE is focused review, not exploration. Evidence already exists from EXPLORE phase. No new evidence gathering.

Exit Criteria:

• All hypotheses have verdict (Confirmed/Refuted/Inconclusive)
• All verdicts have confidence level
• All verdicts cite supporting evidence
• Hypothesis Verdicts table complete

Tools: Read, Grep, memory_search_with_experience

4. CONCLUDE Phase

On Entry:

mcp__haios-operations__cycle_set(cycle="investigation-cycle", phase="CONCLUDE", work_id="{work_id}")

Goal: Synthesize findings, spawn work items, and reconcile epoch artifacts.

Actions:

1. Review findings against original objective
2. Synthesize answer to the investigation question
3. Epistemic Review (MUST) - see section 4a below
4. Identify spawned work items (ADRs, backlog items, new investigations)
5. Create spawned items using /new-* commands with spawned_by: {this_investigation_id}
6. Epoch Artifact Reconciliation (MUST - Session 276) - see below
7. Store findings summary to memory via ingester_ingest
8. Update investigation status: status: complete
9. Populate memory_refs in work item frontmatter

4a. Epistemic Review (MUST)

Before spawning work, categorize all findings into three categories:

Step 1: Categorize findings

Step 2: Render verdict

Step 3: If DEFER

Present the K/I/U summary to the operator using AskUserQuestion:

• Header: "Epistemic Review"
• Question: "Investigation has significant unknowns. Review findings and choose direction."
• Options: "Proceed anyway" / "Investigate more" / "Defer to next session"

After operator responds:

1. MUST immediately write operator decision to CONCLUDE.md "Operator Decision" field BEFORE proceeding to step 4
2. Route based on response:
   • "Proceed anyway" → Continue to step 4 (spawn work normally); unknowns accepted
   • "Investigate more" → Spawn follow-up investigation instead of implementation work
   • "Defer to next session" → Skip spawn; record rationale; close CONCLUDE

If AskUserQuestion fails or times out: treat as "Defer to next session" (fail-safe).

Rationale (WORK-082, Session 372):

• Location inside CONCLUDE preserves investigation context (standalone ceremony loses it)
• Three-level verdict aligns with L3.6 Graceful Degradation (not binary block)
• K/I/U structure aligns with L3.2 Evidence Over Assumption
• DEFER respects L3.4 Duties Are Separated (operator decides on unknowns)

4b. Epoch Artifact Reconciliation (MUST)

Investigations reveal ground truth. Before closing, reconcile findings with epoch structure:

Step 1: Check related chapters

For each chapter referenced in work item (chapter: field or @ references):

Step 2: Check related arc

• If new chapter needed → Add to arc chapters table
• If investigation adds to arc theme → Update arc with findings summary
• Add memory_refs from this investigation

Step 3: Check epoch

• If investigation introduces new decision → Add to EPOCH.md decisions section
• If investigation marks exit criteria complete → Update EPOCH.md checklist
• Add memory_refs from this investigation

Rationale (Session 276): WORK-065/WORK-016 revealed that without this step, chapters stay "Planned" after code exists, findings get buried in WORK.md files, and epoch artifacts drift from reality. Investigations are the natural audit point.

Governed Activities (DONE state):

• file-read: allow
• file-write: allow
• memory-store: allow
• skill-invoke: allow

Exit Criteria:

• Findings synthesized (answer to objective documented)
• MUST: Epistemic review completed (K/I/U table populated with findings — not empty)
• MUST: Verdict rendered and documented (PROCEED/DEFER/INVESTIGATE-MORE)
• If DEFER: Operator consulted via AskUserQuestion and decision recorded in CONCLUDE.md
• Agent verification: Read own CONCLUDE.md to confirm K/I/U table + verdict present before marking CONCLUDE complete
• Work Disposition table complete: every finding-recommended item has disposition (SPAWNED with ID, or DEFERRED with rationale)
• MUST: Epoch artifacts reconciled (chapters, arc, epoch updated if applicable)
• Learnings stored to memory (ingester_ingest called)
• memory_refs populated in work item frontmatter
• Investigation marked complete

Tools: ingester_ingest, Edit, AskUserQuestion, /new-adr, /new-plan, /new-work

5. CHAIN Phase (Post-CONCLUDE)

On Entry:

mcp__haios-operations__cycle_set(cycle="investigation-cycle", phase="CHAIN", work_id="{work_id}")

Goal: Close investigation and route to next work item.

Actions:

1. Close investigation: /close {backlog_id}
2. Query next work: mcp__haios-operations__queue_ready()
3. If items returned, read first work file to check documents.plans
4. Read work item type field from WORK.md
5. Apply routing decision table (see routing-gate skill):
   • If next_work_id is None → await_operator
   • If type == "investigation" OR ID starts with INV- → invoke_investigation
   • If has_plan is True → invoke_implementation
   • Else → invoke_work_creation
6. Execute the action:
   • invoke_investigation -> Skill(skill="investigation-cycle")
   • invoke_implementation -> Skill(skill="implementation-cycle")
   • invoke_work_creation -> Skill(skill="work-creation-cycle")
   • await_operator -> Report "No unblocked work. Awaiting operator direction."

MUST: Do not pause for acknowledgment - execute routing immediately.

Exit Criteria:

• Investigation closed via /close
• Next work item identified (or none available)
• Appropriate cycle skill invoked (or awaiting operator)

On Complete:

mcp__haios-operations__cycle_clear()

Tools: /close, mcp__haios-operations__queue_ready, Read, Skill(routing-gate)

Composition Map

Quick Reference

EXPLORE phase principles:

• Explore freely before constraining with hypotheses
• Query memory for prior work early
• Document sources as you go

HYPOTHESIZE phase principles:

• Hypotheses form FROM evidence, not before
• Each hypothesis must cite supporting evidence
• Define how each will be tested

Key Design Decisions

Phase Templates

For detailed phase guidance, see fractured templates:

Each template defines:

• Input Contract (what must exist before starting)
• Governed Activities (from activity_matrix.yaml)
• Output Contract (what must be produced)

Related

• implementation-cycle skill: Parallel workflow for implementation tasks
• Investigation template: .claude/templates/investigation.md (monolithic, deprecated)
• Fractured templates: .claude/templates/investigation/ (preferred)
• ADR-033: Work Item Lifecycle (DoD criteria)
• /new-investigation command: Creates investigation documents
• /close command: Closes completed investigations
• WORK-037: Investigation that designed this EXPLORE-FIRST pattern
• WORK-061: Implementation of EXPLORE-FIRST pattern