Code Explorer

Iteration 1: Directly answer the question (structural output) Iteration 2: Automatically dig into risks/unknowns found in the answer Iteration 3: Check implicit specs and blind spots in surrounding code

After 3 loops, ask the user whether to continue.

Phase 1: Observe — Analyze Intent

Analyze $ARGUMENTS and determine the combination of analyses to run.

Skill Auto-Composition

Existing skills are auto-invoked based on the question. Users do not need to know individual skill names.

Important: Rather than calling each skill sequentially, independent analyses run as parallel agents simultaneously.

Autonomous Pipeline — From question to HTML in 5 minutes

When this skill is invoked, execute the following pipeline autonomously. No mid-process confirmation needed (only ask after final output whether to go deeper).

Step 1: Scope — Identify the investigation target (30s)

Determine investigation scope from $ARGUMENTS.

Input: "Understand the payment service"
→ Scope: src/services/payment/ and its dependencies
→ target name: payment-service (used in filenames)

Input: src/auth/
→ Scope: all files under src/auth/
→ target name: auth

If scope is too broad (100+ files), split into sub-scopes by directory.

Step 2: Investigate — Parallel agent investigation (2-3min)

Run 3 parallel investigations using Agent tool, save results as JSON files.

First, create .code-explorer/ directory and meta file:

mkdir -p .code-explorer

Write to .code-explorer/{target}-meta.json:

{ "target": "{display name}", "question": "{user question}", "scope": "{scope}" }

Then launch 3 Agents in parallel. Each Agent is instructed to output JSON only.

Important: Explore agents cannot use Write tool. After receiving each Agent's JSON output, use Write tool yourself (main Claude) to save to file.

Agent 1 (structure) — receive output, Write to .code-explorer/{target}-structure.json:

Investigate dependencies of the following scope and output JSON only (no explanation).
Result format: {"nodes": [...], "edges": [...], "paths": [...]}

Schema: harness-engineering/skills/code-explorer/graph-ir-schema.json

nodes elements:
  - id: kebab-case unique identifier
  - type: function|event|guard|action|data (no custom types; skills use action)
  - label: display name (60 chars max)
  - detail: one-line description
  - file: relative path from project root
  - line: main line number
  - layer: architecture layer (see rules below)
  - risk: CRITICAL|HIGH|MEDIUM|LOW (only when applicable)
  - metadata: { implicitSpecs: [...], breakageScenarios: [...] } (only when applicable)

edges elements:
  - source → target is execution order (caller → callee). Do not reverse.
  - type: calls|reads|writes|triggers|references|side-effect
  - reads = actual import/require/file reads only. Conceptual dependencies use references

paths elements:
  - id, name, nodes (array of node ids), type (execution|guard|breakage|error|side-effect)
  - risk: paths with unguarded breakage are HIGH or above

Layer classification: routes/api→presentation, services→service, domain/models→domain,
  repositories/db→infrastructure, config→data, test→test, scripts→script,
  .github→ci, hooks/middleware→hook. If no match, use directory name as-is.

Scope: {scope}

Agent 2 (behavior) — receive output, Write to .code-explorer/{target}-behavior.json:

Read code in the following scope and output implicit specs and breakage scenarios as JSON (no explanation).
Result format: {"implicitSpecs": [...], "breakagePerNode": {...}}

implicitSpecs elements:
  - rule: implicit spec (string)
  - source: file:line
  - type: convention|design-decision|assumption|platform-behavior|tuning|gap
  - risk: risk description (only when applicable)

breakagePerNode: map of node id → array of breakage scenario strings
  Categories: NULL/RACE/TIMEOUT/STATE/ORDER

Scope: {scope}

Agent 3 (gaps) — receive output, Write to .code-explorer/{target}-gaps.json:

Output untested, unreachable, and undocumented code in the following scope as JSON (no explanation).
Result format: {"blindSpots": [...]}

blindSpots elements:
  - type: untested|no-test|dead-code|undocumented|no-owner|single-point|gap|role-unclear|stale-docs
  - target: target name
  - file: relative path
  - description: description

Scope: {scope}

Step 3: Merge — Integrate Agent outputs (10s)

After all 3 Agents complete, use the CLI merge to integrate into a single Graph IR:

node harness-engineering/skills/code-explorer/explorer-cli.js merge \
  .code-explorer/{target}-meta.json \
  .code-explorer/{target}-structure.json \
  .code-explorer/{target}-behavior.json \
  .code-explorer/{target}-gaps.json \
  -o .code-explorer/{target}-graph.json

merge automatically:

• Uses structure nodes/edges/paths as base
• Merges behavior breakagePerNode into each node's metadata.breakageScenarios
• Places behavior implicitSpecs at top level
• Places gaps blindSpots at top level
• Auto-builds layers map from nodes
• Auto-generates followUpQuestions from implicitSpecs and blindSpots

Step 4: Pipeline — Validate → Generate → WCAG → Open (30s)

node harness-engineering/skills/code-explorer/explorer-cli.js pipeline \
  .code-explorer/{target}-graph.json --open

This executes in order:

1. validate — schema + referential integrity check (stop on failure → fix Graph IR, re-run)
2. generate — embed Graph IR in template and generate HTML
3. wcag — WCAG 2.2 lint + auto-fix (stop on failure)
4. open — open in browser

Error Recovery

CLI Command Reference

CLI=harness-engineering/skills/code-explorer/explorer-cli.js

# Merge Agent outputs
node $CLI merge  meta.json structure.json behavior.json gaps.json -o graph.json

# Full pipeline (validate → generate → wcag → open)
node $CLI pipeline  .code-explorer/{target}-graph.json --open

# Individual steps
node $CLI validate  .code-explorer/{target}-graph.json
node $CLI generate  .code-explorer/{target}-graph.json
node $CLI wcag      .code-explorer/{target}-explorer.html --fix

Step 5: Report — Text summary output

After opening the HTML in browser, display a text summary in terminal:

## Understanding Map: {target}

Nodes: {n} | Edges: {e} | Paths: {p} | Risks: {r_high} HIGH, {r_med} MED

### Top Risks
1. [HIGH] {description} ({file}:{line})
...

### Implicit Specs
1. {rule} — {source}
...

### Follow-up Questions
- [ ] {question}
...

Interactive UI: .code-explorer/{target}-explorer.html
Type 'continue' to explore follow-ups, or ask a new question.

Step 6: Explore Loop — Deep-dive (optional)

When the user says continue, auto-investigate Follow-up Questions:

1. Run additional Agent investigations for each question
2. Merge results into existing Graph IR (add nodes/edges)
3. Regenerate HTML
4. Present new Follow-up Questions

Auto-stop after 3 loops and ask user to confirm continuation.

Phase 2: Orient — Structured Analysis

Analysis Type: Call Tree

getUserById (src/repository/user.ts:42)
├── caller: UserService.fetchProfile (src/service/user.ts:18)
│   └── caller: ProfileController.get (src/api/profile.ts:25)
└── caller: AdminService.lookupUser (src/service/admin.ts:67)

Analysis Type: Impact Trace

[Direct] src/service/user.ts:updateUserEmail
  ├─→ [DB] users.email — unique constraint, may conflict
  ├─→ [Side Effect] isVerified → false
  │     ├─→ [UI] verified badge disappears
  │     └─→ [API] verified-only endpoints → 403
  └─→ [Event] UserEmailChanged → NotificationService

Analysis Type: Breakage Scenarios

1. [NULL] user.paymentMethod is undefined
   Trigger: Guest checkout without payment setup
   Guard: No null check — TypeError at payment.ts:45

2. [RACE] Concurrent payment for same order
   Trigger: Double-click submit
   Guard: No idempotency key — duplicate charge

Analysis Type: Implicit Spec

Rule 1: Session expires after 30min inactivity
  Source: session.ts:23
  Contradicts: config.ts SESSION_TTL=3600 (1hr)

Rule 2: Account locks after 5 failed logins
  Source: login.ts:67
  Lock duration: permanent (no auto-unlock)

Analysis Type: Blind Spot Detection

UNTESTED: payment.ts:processRefund — 0 coverage
DEAD CODE: legacy_export.ts — no imports
UNDOCUMENTED: src/jobs/ — 4 files, 0 docs
SINGLE POINT: config/secrets.ts — 23 dependents, 1 contributor

Phase 3: Decide — Auto Deep-Dive Decision

Deep-dive runs automatically but always stops after 3 iterations to confirm with user.

Exploration Memory

Within-Session Accumulation

Graph IR accumulates in .code-explorer/. Follow-up questions in the same session add nodes/edges to existing Graph IR (no re-analysis).

Cross-Session Handoff

Important implicit specs or design decisions found during exploration are saved to MEMORY.md after user confirmation. Never saved automatically.

Active Learning Integration

Before generating the Interactive HTML, optionally ask the user's hypothesis:

Target: PaymentService

Your prediction first (skippable):
- Where do you think this function's callers are?
- What edge cases do you expect?

(Press Enter to skip and show results directly)

If the user enters a prediction: add to Graph IR as prediction field, overlay "prediction vs reality" in Interactive HTML, highlight nodes/edges that differ from prediction.

Related Skills

• code-journey: Step-by-step execution flow visualization (used internally)
• bug-investigation: Known bug root cause analysis (used in deep-dive)

Gotchas

See gotchas.md in this directory for known pitfalls and recurring mistakes when using this skill.