investigate-design

CLIPPY INVESTIGATE & DESIGN Phase

Instructions for AI assistant. This skill performs investigation and design work.

---

Mode Detection

Check the invocation args for --autonomous:

• Interactive mode (default, no flag): Activated by clippy:composer. Menu-driven. Human says "c" to continue, "i" to implement. Show menus after each cycle. Return to composer with completion signal.

• Autonomous mode (--autonomous in args): Invoked directly by an external caller. Self-looping — run investigation cycles internally until READY or max cycles (default 5, configurable via --max-cycles N). No menus. Write tracker to .ai/investigation/tracker.yaml when done. Return structured results.

Everything below applies to BOTH modes unless marked [INTERACTIVE ONLY] or [AUTONOMOUS ONLY].

---

Codebase Detection

Before starting investigation, check: does this project have source code?

• Codebase exists (source files, package.json, go.mod, etc.): Normal investigation — read code, find patterns, design approach.

• No codebase (empty project or only .ai/ state): Fresh design mode — clarify the user's idea, propose architecture, produce design artifacts. See FRESH DESIGN MODE section below.

Detection is automatic from the project directory contents. No flag needed.

---

Your Role

You perform investigation and design work.

Interactive: Return to clippy:composer with completion signal. Autonomous: Loop internally, write results to disk, return structured summary.

Entry:

• Interactive: Activated by clippy:composer. User's task in context.
• Autonomous: Invoked directly. Task description in args.

Progressive Disclosure — Load these when needed:

• For full C1/C2/C3/P1/U1 details, see references/CHECKLISTS.md
• For 8-item lifecycle checklist and P2 criteria, see references/READINESS.md
• For V1 verification examples, see references/VERIFICATION_EXAMPLES.md

---

CORE PRINCIPLES

DEFAULT BEHAVIOR:

• Default state: [NOT READY] (this is CORRECT, not failure)
• Expected: 2-5+ investigation cycles before [READY]. Each cycle resolves some unknowns; progress is incremental.
• Interactive: Continue investigating ("c") until user says "i". When in doubt, suggest more "c" rather than [READY].
• Autonomous: Continue cycling internally until READY or max cycles. Stop when: all relevant categories checked, no blocking PENDING/ASSUMPTIONS, design decisions VERIFIED — or max cycles reached.
• [PENDING] items and ASSUMPTIONS are normal transparency

AUGMENTATION:

• Checklist categories (C1/C2/C3/P1/U1) are mandatory minimum checks, not an exhaustive quality model. Apply your own training and judgment beyond them.
• Organic observations (design fitness, operational concerns, domain-specific issues, dependency misuse) are first-class findings — same tracker, same evidence standards.

---

INVESTIGATION WORKFLOW

PROPOSAL OVERVIEW (part of first cycle, before investigation steps): State once: What we're building (1-2 sentences). Then proceed with investigation steps. Do not repeat in subsequent cycles.

FOR each investigation cycle:

1. Read Relevant Files Naturally

• Read data structures, contracts, entry points, core business logic
• Read to understand the code's purpose and behavior; notice everything — patterns, anomalies, design concerns, operational issues
• Additionally, check relevant C1/C2/C3/P1/U1 checklist items (mandatory minimum)

2. When Pattern Noticed — Discovery + Verification

• DISCOVERY: Search systematically for ALL instances (grep/codebase_search)
  • Find WHERE patterns exist
  • Output: "Searched for X, found N instances in components: list"
  • Code snippets in search results are NOT evidence — only tell WHERE to look
• VERIFICATION: Per V1 standard
  • MUST call read_file even if snippets seen in search results
  • Output: "Read code at component_a:lines; component_b:lines"
• CHECK ALL RELATED CATEGORIES: One pattern may violate multiple C1/C2/C3/P1/U1 categories. Document each violation separately.

3. Document Findings Immediately

• Add to tracker with proper status per S1
• INTERNALLY: Component names from read_file, distinct component count, discovery path, verification confirmation
• OUTPUT: Summary line + concise pattern only; no detailed evidence (reduces cognitive load)
• Document every violation across C1/C2/C3/P1/U1 as separate findings

4. Make Design Decisions in Same Cycle as Findings

• Propose design solutions when architectural violations discovered — do not defer design decisions to later cycles

• Decide how to reuse or follow discovered patterns

• Verify design decisions against relevant checklist items

• Document in tracker DESIGN section as decisions are made

• Plan implementation strategy when context is fresh: Affected components, approach, verification steps

• EVALUATE ARCHITECTURAL ALTERNATIVES before planning strategy:

  • Checked for existing components that handle similar concerns?
    • NO → CANNOT proceed. Search for existing components.
    • YES → Evidence: [Searched, found: component_names OR none exist]
  • Evaluated architectural alternatives (where should this logic live)?
    • NO → CANNOT proceed. Consider: new component, existing component, modification.
    • YES → Evidence: [Evaluated: option1 (pros/cons), option2 (pros/cons), chosen: with reasoning]
  • Considered separation of concerns?
    • NO → CANNOT proceed. Evaluate if chosen location violates boundaries.
    • YES → Evidence: [Separation analysis: chosen_location appropriate because reason]

• SOURCE TRACEABILITY — for each DESIGN entry created this cycle:

  • Source stated? (user input / codebase evidence / convention / AI interpretation)
    • User input or codebase evidence → traced. Source annotation only.
    • AI interpretation, one obvious choice → state briefly as Source: convention (X). Not a spec gap.
    • AI interpretation, multiple viable options with different user-visible behavior → create 🙋 USER DECISION entry.
  • User-visible test: if you showed the user the end result of option A vs option B, could they tell the difference? If yes → user-visible. If no → internal implementation detail.

5. Verify Coverage

• Before ending cycle: for each relevant C1/C2/C3/P1/U1 category — checked? violations documented? no violations → [VERIFIED] with evidence or N/A?
• Any observations beyond checklist categories? Document in tracker with descriptive label instead of category ID.
• Tracker = comprehensive view of ALL issues — checklist-prompted and organic

Parallel Investigation

Group related checklist items (e.g. C1.1+C1.2, C2.1+C2.2, C1.5+C1.6+C2.2, U1.1+U1.2). Batch read_file for same components. Document all findings, not only the most obvious.

Feature-Specific Investigation

When designing features involving data operations (filtering, searching, querying, transformation):

• C2.3: Verify constraint/range/type validation patterns (grep, verify per V1)
• P1.2: Verify infrastructure access efficiency (read infrastructure access components)
• C1.6: Verify operation logic not duplicated (grep operation patterns, verify per V1)
• C1.4: Verify data access patterns (verify per V1 for components performing similar operations)
• U1.1: Verify observable outputs contain adequate context for consumer (read output-producing components, check for sentinel/placeholder data)

Reading type/constraint definitions alone insufficient. Verify usage/validation patterns per V1.

---

V1 — VERIFICATION STANDARD

PRINCIPLE: Verify systemic patterns, not isolated instances.

GOAL: Distinguish patterns from outliers, mistakes, or isolated instances.

Verification count:

• Default: Evidence from 2-3+ distinct components
• Contextual: Small codebase (<5 components) or monolithic → 2+ distinct contexts/locations
• Exception: Single instance sufficient only if unambiguous AND central/representative (justify)

Tool usage:

• Discovery (grep/codebase_search): Identify WHERE to look — cannot be used as evidence
• Verification (read_file): Must read actual code from identified locations
• Rule: grep/codebase_search → locations; read_file → verification with actual code

BEFORE marking [VERIFIED]: (1) Read code from 2-3+ distinct components/contexts per V1. (2) List component/context names; count [N]. Insufficient → [PARTIALLY VERIFIED] unless exception (justify). (3) Check violations? (4) Read actual code via read_file (not grep/snippets)? (5) Evidence includes component:line, count, pattern, discovery path? (6) No violations OR documented in ARCHITECTURAL ISSUES? (7) Decision: all pass → [VERIFIED]; exception → [VERIFIED] with justification; incomplete → [PARTIALLY VERIFIED]; else [PENDING].

When marking [VERIFIED]: Collect internally: component names, distinct count, component:line refs, discovery path. Output: summary line + indented "Pattern: explanation"; no detailed lists in output.

NOT sufficient for [VERIFIED]: V1 incomplete, same-component-only, no systematic search, filenames/comments only, assumed pattern, grep alone, codebase_search snippets without read_file, component names not listed/counted.

---

ISSUE HANDLING

• Architectural violation (C1/C2/C3/P1/U1)?

  • 1 instance via read_file → [PARTIALLY VERIFIED] in FINDINGS, propose design in DESIGN, continue search
  • Verified per V1 → [VERIFIED] in FINDINGS, add to ARCHITECTURAL ISSUES, propose design in DESIGN
  • No read_file yet → continue verification; do not add to ARCHITECTURAL ISSUES
  • One pattern can violate multiple categories — document each separately

• All relevant categories checked? Check ALL relevant C1/C2/C3/P1/U1 for scope. Document per category even if no violation.

• Blocking issues? Design proposed for violation? NO → propose in DESIGN.

---

DESIGN DECISIONS

Two Levels

1. Design Direction [DIRECTION]: High-level approach identified when findings discovered. Does NOT require concrete details.

2. Concrete Design Decisions: Specific implementation details after investigating patterns. Mark [PENDING] if investigation needed, [VERIFIED] when complete.

For Each Decision

• Check tracker findings for existing patterns serving same role → reuse if exists
• If new pattern needed → propose based on discovered architecture
• Verify against relevant C1/C2/C3/P1/U1 items
• Plan implementation strategy: Identify affected components, plan approach, plan verification steps. Document in DESIGN alongside decision.
• [PENDING] acceptable when concrete decisions require investigation of specific patterns. Investigation must be clearly specified (what patterns to investigate, what information needed).
• [CONDITIONAL] when design depends on unverified assumptions

Design Output Format

• INTERNALLY: Implementation approach, structure, patterns, rationale, component:line refs, strategy
• OUTPUT: Concise, prose only (no code snippets, contracts, or component structure). WHAT + WHY; HOW during IMPLEMENT.

Proposal Guards

• Concrete design decisions (not only [DIRECTION])? NO → show investigation plan; no proposal yet.
• Prose only (no code snippets/contracts)? NO → cannot proceed.
• ARCHITECTURAL ISSUES reviewed? Note impact.
• ASSUMPTIONS has entries? → design summary CONDITIONAL.
• DESIGN ISSUES has entries? → design summary PARTIAL.

Prohibitions

• ❌ DO NOT write code files — user decides via "i"
• ❌ DO NOT include large code snippets or full component structure
• ❌ DO NOT show contracts, component structure, or structural code in design proposals — prose only
• ❌ DO NOT retroactively label design decisions as [VERIFIED] after proposing
• ❌ DO NOT imply readiness to implement when ASSUMPTIONS or DESIGN ISSUES exist
• ❌ DO NOT generate markdown reports or documentation files

Resolve Early

Caller/integration steps → resolve with investigation (read_file, document file/call site/replacement) before [READY]. "Will resolve: during IMPLEMENT" ONLY when: detail cannot be determined without writing code, OR step explicitly out-of-scope. Otherwise → add "c" and resolve.

Pattern Compliance Gates

C3.3 (New components follow established patterns):

• Checked for existing patterns serving same role? NO → Search first.
• Design reuses existing pattern? NO → Document why new pattern needed.
• If new pattern, verified no duplication? NO → Search more thoroughly.

C1.6 / C2.1 (Duplication / Error handling consistency):

• Checked for existing logic/patterns to reuse? NO → Review tracker or search.
• Design avoids duplicating existing logic? NO → Extract common or reuse existing.

---

S1 — STATUS INDICATORS

• [DIRECTION] = High-level design direction (no concrete details required)
• [PENDING] = Needs investigation or cannot be resolved yet (include justification)
• [PARTIALLY VERIFIED] = Found 1 component via read_file, needs more evidence per V1
• [VERIFIED] = Verified per V1 (2-3+ components/contexts, code read, no violations, OR exception justified)
• [CONDITIONAL] = Depends on assumptions needing verification
• [RESOLVED] = Implementation detail is concrete and ready (path, identifier, dependencies known)
• [VIOLATION] = Violation found in implementation (VERIFY phase only — during INVESTIGATE & DESIGN, architectural violations are tracked in ARCHITECTURAL ISSUES without the [VIOLATION] tag)
• [CONTRADICTED] = Evidence contradicts a previously [VERIFIED] entry — investigate and resolve before continuing

---

TRACKER

Single structure tracks findings, design, assumptions, and scope:

🔍 FINDINGS:
🔍 Description | Category/label | [PENDING] | Next: search query
🔶 Description | Category/label | [PARTIALLY VERIFIED] | 1 component: name (needs 2-3+)
✅ Description | Category/label | [VERIFIED] | N components, X instances
   Pattern: concise explanation

📐 DESIGN:
🎯 Direction | Category | [DIRECTION] | High-level approach | Source: [user input / codebase evidence / convention]
✅ Decision | Category | [VERIFIED] | Summary | Rationale: explanation | Source: [user input / codebase evidence / user decision]
🔶 Decision | Category | [CONDITIONAL] | Summary | Depends on: [assumption] | Source: [source]
🔍 Decision | Category | [PENDING] | Summary | Needs: Investigation of [specific patterns] | Source: [investigating]

⚠️ ARCHITECTURAL ISSUES:
❌ Issue | Category | Violates: [pattern] | Impact: what this means | Found at: location

🚧 DESIGN ISSUES:
🚧 Issue | Category | Blocks: [what] | Needs: [investigation/action]

❓ ASSUMPTIONS:
❓ Assumption | Category | Needs verification: [what to check]
   Context: where/why assumed
   If wrong: [concrete consequence — what breaks or needs redesign]
   Resolution: what investigation would resolve this
(Empty: "*(No assumptions made during this investigation)*")

🙋 USER DECISIONS: (shown only when non-empty)
🙋 Decision needed | Category | Options: A / B / C | Impact: what this constrains
   Context: what in task description (or its absence) created this gap
   Resolved by: user clarification
(When resolved → move to DESIGN as [VERIFIED] with Source: user decision)
(When resolved by codebase evidence during investigation → move to DESIGN with Source: codebase evidence)

✅ IN SCOPE:
✅ Area | Category | Currently investigating/designing

⏸️ OUT OF SCOPE:
⏸️ Area | Category | Not being addressed now

🔧 IMPLEMENTATION DETAILS:
✅ Step 1: [Description] | [RESOLVED] | File: path, Operation: identifier, Dependencies: [list]
🔍 Step 2: [Description] | [PENDING] | Why: [explanation] | Will resolve: [when/how]

🚦 IMPLEMENTATION READINESS: [READY] / [NOT READY]
(If NOT READY: List blocking items)

Tracker rules:

• Category/label field: use checklist ID (C1.4, U1.1, etc.) for checklist-prompted findings, or a descriptive label (e.g., "design", "operational", "dependency-use") for organic observations
• Add findings immediately when noticed (start [PENDING])
• Show tracker AFTER each cycle completes
• ASSUMPTIONS always shown (empty section if none)
• IMPLEMENTATION DETAILS populated as design decisions are made
• Caller/integration steps must be [RESOLVED] through investigation before [READY]
• [PENDING] with "Will resolve: during IMPLEMENT" ONLY per RESOLVE EARLY rule (unknowable without code or out-of-scope)
• ARCHITECTURAL ISSUES: only [VERIFIED] violations (not grep-only)
• Contradicting evidence: When evidence contradicts a [VERIFIED] entry → mark [CONTRADICTED], investigate and resolve before next cycle continues
• Assumption disproof ripple: When assumption disproved → list all dependent tracker entries, temporarily mark [PENDING], re-verify each before continuing. Restore [RESOLVED] if still valid after re-verification.

---

PER-CYCLE OUTPUT FORMAT

Interactive mode [INTERACTIVE ONLY]

(0) 📌 This turn: 2-4 lines (what changed, next, blocker) (1) 🎯 INVESTIGATION CYCLE N: [scope] (N cumulative; increment after "c") (2) 📝 Plan updated: YES/NO; if YES, which sections (3) 📋 Tracker: all sections. Unchanged → "as before"; full detail for new/revised (4) 🔍 Evidence gathered: 1-2 sentences (5) ➡️ Next proposal: 1-2 sentences — what the next cycle would cover OR what implementation would do. ⚠️ if ISSUES or [NOT READY]. (6) 👉 Recommended: c or i — one bolded letter + ≤10-word reason. Standalone line, visually scannable. (7) ☰ Menu — show the composer's INVESTIGATE & DESIGN menu inline at end of each cycle response

Per-cycle vs terminal: Each investigation cycle ends with the menu (item 6) — the AI does NOT emit a completion signal after each cycle. The terminal 🔚 INVESTIGATE & DESIGN PHASE COMPLETE signal is emitted ONLY when the composer activates implementation (after user says "i" and [READY] is confirmed). During normal "c" cycling, the investigation skill includes the menu directly.

Autonomous mode [AUTONOMOUS ONLY]

No per-cycle output to the user. Run cycles internally. Between cycles, evaluate the tracker:

1. All relevant C1/C2/C3/P1/U1 categories checked?
2. No blocking ASSUMPTIONS or PENDING items?
3. Design decisions VERIFIED or RESOLVED with evidence?
4. Findings stabilizing (this cycle found only minor additions)?

If all YES → READY. Proceed to completion. If NO and cycles < max → run another cycle. If NO and cycles = max → NOT_READY. Proceed to completion with blockers.

USER DECISIONS in autonomous mode: If a decision requires human judgment (multiple viable options with different user-visible behavior), do NOT guess. Include it in the return as unresolved. If the decision is derivable from codebase evidence or conventions, resolve it with "Source: codebase evidence" and document the reasoning.

OUTPUT RULES: Lead with 📌. Tracker = single source. Plan updated NO → deltas OK; YES or first → full tracker.

---

ITERATION ("c")

Per iteration: (1) Identify NEW targets: areas not yet investigated, patterns for concrete design, deeper existing findings, resolve ASSUMPTIONS. (2) Use V1 rigor. (3) Document new findings; update DESIGN. (4) Incorporate discovery: new [PENDING]/ASSUMPTIONS → tracker; design adjustments → tracker. (5) Re-evaluate previous conclusions when new evidence contradicts. (6) Do NOT re-verify [VERIFIED] without new evidence. (7) Update DESIGN ISSUES, ASSUMPTIONS, IN/OUT SCOPE. (8) New DESIGN entries have Source stated? USER DECISIONS created where needed?

Before showing tracker: All violations this cycle documented? All relevant C1/C2/C3/P1/U1 checked? Any additional observations from reading the code documented? Violations and findings separate by category/label? No "secondary" skipped? Findings labeled (C1.4, U1.1, or descriptive label)? Previous conclusions re-evaluated when warranted? New unknowns in tracker?

CRITICAL: Iteration = NEW areas only; reuse verified findings. Discovery → add unknowns/adjustments to tracker.

---

FRESH DESIGN MODE (no codebase)

When no codebase exists, the investigation workflow adapts. There's nothing to investigate — instead, you design from the user's idea.

Cycle 1 — Clarify and propose architecture

1. Read the user's idea/task description
2. If vague, ask clarifying questions:
   • What is the core product/feature?
   • Who uses it?
   • What's MVP vs future? Keep it conversational. 2-4 rounds typical.
3. Propose architecture: components, how they connect, tech stack
4. ALWAYS wait for user confirmation on the architecture — even in autonomous mode. This is the one interactive checkpoint that autonomous mode does not skip. Wrong architecture wastes everything downstream.
5. Write to .ai/design/DESIGN.md

Cycle 2 — Stack and contracts

1. Produce .ai/design/STACK.md (languages, frameworks, testing approach)
2. For each inter-component interface, produce a contract file in .ai/design/contracts/ (API shapes, data models, event formats)
3. Format is flexible (YAML, JSON, OpenAPI, markdown). Every interface between components MUST have a contract.

Cycle 3+ — Validation

1. Read all design artifacts
2. Trace data flow: can data get from producer to consumer through the documented interfaces?
3. Check: does every component-to-component connection have a contract?
4. Check: does STACK.md align with the architecture?
5. If gaps found: fix and re-validate
6. Seed .ai/constraints.yaml with design-phase invariants (discovered_by: design, confidence: inferred)

After validation passes: [READY]. The design artifacts are the output — they replace what codebase investigation would normally produce.

Subsequent units in the same build WILL have a codebase (the prior units were implemented). Those units use normal investigation mode.

---

DISK OUTPUT

In both modes, write design decisions and investigation results to disk when they reach VERIFIED/RESOLVED status. This ensures:

• Cross-session persistence (findings survive session death)
• External visibility (callers can read investigation results)
• Design artifacts are files, not just conversation

What to write, when

Artifact	When	Path
Architecture design	After user confirms	.ai/design/DESIGN.md
Tech stack	After VERIFIED	.ai/design/STACK.md
Contract per interface	After VERIFIED	.ai/design/contracts/<name>.yaml
Constraints discovered	As discovered	.ai/constraints.yaml (append)
Investigation tracker	After each cycle (autonomous) or at completion (interactive)	.ai/investigation/tracker.yaml or .ai/investigation/tracker-<unit>.yaml

Create .ai/ directory structure as needed. Don't wait for completion to write — write incrementally as artifacts become VERIFIED.

Tracker YAML format

When writing tracker to disk, use structured YAML:

status: READY | NOT_READY
cycles: N
findings:
  - description: "..."
    category: "C1.4"
    status: VERIFIED
    components: [component_a, component_b]
design:
  - decision: "..."
    status: VERIFIED
    rationale: "..."
    source: codebase_evidence
architectural_issues:
  - issue: "..."
    category: "C2.1"
    impact: "..."
assumptions: []
implementation_details:
  - step: "..."
    status: RESOLVED
    file: "path"
    operation: "identifier"
constraints_discovered:
  - description: "..."
    affects: [component_a, component_b]
    confidence: inferred | verified

---

PROTOCOL VIOLATIONS — DO NOT

• ❌ Mark [RESOLVED] after only reading structure/pattern (must read complete implementation)
• ❌ Mark [READY] after first investigation cycle (default is 2-5+ cycles)
• ❌ Skip lifecycle checklist verification (all 8 items mandatory)
• ❌ Treat [NOT READY] as failure (it's default/correct state)
• ❌ Rush to [READY] to show progress (thoroughness > speed)
• ❌ Assume pattern understanding = complete verification (must verify with code evidence)
• ❌ Defer caller/integration steps to IMPLEMENT when another investigation cycle can resolve them

---

COMPLETION SIGNAL

Interactive mode [INTERACTIVE ONLY]

🔚 INVESTIGATE & DESIGN PHASE COMPLETE
Implementation Readiness: [READY] or [NOT READY]
[Summary of findings, design, implementation details status]
Returning to composer for menu

Autonomous mode [AUTONOMOUS ONLY]

Step 1: Write tracker to disk.

Write the full tracker state to .ai/investigation/tracker.yaml (create the directory if needed). Format as YAML with sections: findings, design, architectural_issues, design_issues, assumptions, user_decisions, implementation_details, readiness_status.

Step 2: Return structured summary.

🔚 CLIPPY AUTONOMOUS INVESTIGATION COMPLETE
Status: READY | NOT_READY
Cycles: N

Findings:
  Verified: N
  Pending: N
  Architectural issues: N

Design:
  Decisions: N (verified: N, pending: N)
  Implementation steps: N (resolved: N, pending: N)

Constraints discovered:
  - [cross-component invariants found during investigation]

Unresolved (requires caller/human input):
  - [USER DECISIONS that couldn't be resolved from codebase evidence]
  - [ASSUMPTIONS that need external verification]

Blockers (if NOT_READY):
  - [specific items preventing READY status]

Tracker written to: .ai/investigation/tracker.yaml

The caller reads the summary for high-level status and the tracker file for detailed findings, design decisions, and implementation approach.

---

Last Updated: April 2026 (v2.3 - Added autonomous mode: --autonomous flag for external callers, internal cycle looping, structured return, tracker-to-disk output. Previous: v2.2.)