SKILL.md

When to Activate

• Before proposing any fix, change, or solution
• When asked to investigate a problem, behavior, or codebase area
• When another skill (codi-audit-fix, codi-guided-execution) requires investigation
• When you are uncertain about actual behavior — not assumed behavior
• Standalone: “Investigate X before we change it”

Skip When

• You already have direct, fresh tool output from this session that answers the question
• The user wants to write new code or features — use codi-plan-writer
• The investigation is already complete and the next step is a fix — move to codi-verification
• The question is about general concepts, not this codebase’s actual behavior — answer from docs/knowledge directly

The Iron Law

No conclusions without evidence. No evidence without tool usage. No tool usage without a question to answer.

No assumptions. No memory. No “this should work because…”. Tool output only.

The Investigation Protocol

Follow these 5 steps in order. Do not skip steps.

Step 1: FRAME

Write down explicitly:

• What are you investigating?
• What specific question are you trying to answer?
• What would a definitive answer look like?

If you cannot state the question clearly, do not proceed. Clarify with the user first.

Step 2: SEARCH

Use tools in this priority order. Stop when you have sufficient evidence — do not over-search.

1. graph-code MCP (if available) — understand structure, relationships, dependencies, call graphs
2. Grep / Glob — find specific patterns, file locations, symbol usages across the codebase
3. Read — examine actual content of identified files, functions, configs
4. Tests — run existing tests to observe actual behavior; read test assertions as specifications
5. Web research — only for external dependencies, third-party APIs, or published standards

For each tool use, state the question it answers before running it.

Step 3: COLLECT

Build an evidence table from your findings:

Add one row per distinct finding. If a finding cannot be sourced to a tool output, it does not belong in the table.

Step 4: ANALYZE

Review the evidence table and separate:

• Confirmed facts — directly proven by tool output (High confidence)
• Inferences — reasonable deductions from confirmed facts (Medium confidence, label clearly)
• Assumptions — not yet verified, requires more evidence (Low confidence, flag these)

Compare actual behavior (what you found) vs intended behavior (what the code should do). State the gap explicitly.

If assumptions remain after reasonable investigation, surface them rather than guessing.

Step 5: REPORT

Present your findings in this structure:

Question investigated: [The question from Step 1]

Evidence collected: [The table from Step 3]

Analysis:

• Confirmed: [list facts]
• Inferred: [list deductions, labeled as inferences]
• Unverified: [list remaining assumptions]

Conclusion: [Answer to the question, with confidence level]

Open questions: [What couldn’t be determined and what tool/action would resolve it]

What Counts as Evidence

Valid evidence:

• Tool output from this session (grep results, file content, test output, MCP responses)
• Test results showing actual pass/fail behavior
• File content confirming actual implementation
• Git history showing when/why something changed
• Documentation confirming intended behavior

Not valid evidence:

• Memory from previous sessions or conversations
• “I assume it works because…”
• Code that looks correct without running it
• Positive claims from earlier in this session without re-verification

Red Flags

These thoughts mean STOP — you are about to skip evidence gathering:

Integration

• Use in codi-audit-fix Phase 2 before evaluating each item.
• Use in codi-guided-execution Step 4 before validating each step.
• Feeds into codi-verification — evidence gathered here is the input to the verification gate.
• Use in codi-debugging Phase 1 (Observe) for structured evidence collection.