/intelligence-investigator

name: intelligence-investigator
description: |
  Generate intelligence briefings for the planning dashboard. Use this skill
  whenever a request file appears in `.planning/console/inbox/pending/` whose
  `type` field starts with `intelligence.` (refresh_briefing, triage_finding,
  snapshot_diff, investigate_section, dismiss_finding). The skill reads the
  per-project KB at `.gsd/intelligence/intelligence.db`, synthesizes a briefing
  with a causal hypothesis + acknowledged uncertainty + confidence label and
  ranked moves, then writes the result back to the KB. Always trigger this
  skill for these request types — do not generate briefings manually.
version: 1.0.0
format: 2025-10-02
triggers:
  - "console-inbox request type starts with intelligence.* (refresh_briefing, triage_finding, snapshot_diff, investigate_section, dismiss_finding)"
updated: 2026-05-02
status: ACTIVE
allowed-tools: Read, Glob, Bash(sqlite3:*), Bash(git:*), Bash(node:*), Bash(bun:*), Write

Intelligence Investigator

You are responsible for generating planning briefings for the GSD intelligence dashboard. The dashboard surfaces these briefings to the developer at the start of every planning meeting. You run inside a gsd-skill-creator session that is already watching `.planning/console/inbox/pending/`.

When to activate

Activate when you find a file matching `req_*.json` in `.planning/console/inbox/pending/` whose `type` field starts with `intelligence.`:

• `intelligence.refresh_briefing` — full project briefing refresh
• `intelligence.triage_finding` — single finding deep-dive
• `intelligence.snapshot_diff` — explain what changed between two snapshots
• `intelligence.investigate_section` — investigate a specific section of code
• `intelligence.dismiss_finding` — record a dismissal with rationale

Process

1. Parse the request

Read the request file. Extract `id`, `type`, `project`, `branch`, `payload`, `respond_to`, `timeout_hint_ms`. The request fields define the scope:

• `payload.since_snapshot` — for diff-based requests
• `payload.scope` — list of section/file globs to focus on
• `payload.conversation_text` — recent dashboard discussion (already redacted)
• `payload.finding_id` — for triage requests

2. Load KB context

Run `bash scripts/load-kb-context.sh <project>` to extract a redacted JSON context summary. The script:

• Reads top 30 findings by `severity × confidence` from the per-project DB
• Reads in-flight bundles + decisions
• Reads recent meeting record paths (last 3)
• Reads recent snapshot diffs (last 3)
• **Redacts secrets** (API keys, tokens, password fragments, SSH keys) before

emitting context (S14, D-25-31)

• **NEVER** emits raw source-file content (D-25-30)

The output is structured JSON; parse it before reasoning.

3. Synthesize briefing

Following `references/briefing-format.md`, write a briefing of 2-3 paragraphs that:

1. Opens with what's currently happening (1-2 sentences) 2. Proposes at least one **causal hypothesis** ("Coupling spike between X and Y is probably driving the held gate, because…") 3. Acknowledges at least one **uncertainty** ("It's unclear whether the calibration modules can land before the gate clears") 4. Ends with a **confidence label**: `low`, `medium`, or `high` (See `references/confidence-calibration.md` for guidance)

A briefing without a causal hypothesis or without an acknowledged uncertainty fails verification. Do not produce summary-only briefings.

4. Rank suggested moves

Following `references/move-ranking.md`, propose 3-5 ranked next moves. For each:

• **rank** (1 = highest priority)
• **title** (action-oriented: "Investigate X", "Clear Y", "Pick up Z")
• **kind** (`research`, `vision`, `review`, or `analyze`)
• **rationale** (1-2 sentences explaining *why this move now*, citing source findings)
• **expected_unblocks** (what becomes possible if this move succeeds)
• **source_findings** (list of finding IDs that motivated this move)

A move without a rationale fails verification. A move that doesn't reference any source findings is acceptable only if it's a forward-looking move (e.g., "Snapshot diff to see what's drifted") — its rationale must explicitly note "no prior evidence".

5. Self-check the briefing

Run `bun scripts/verify-briefing.ts <briefing-json-path>` (or `node` if bun is unavailable). Exit 0 = pass; exit 1 = fail with violation list.

If self-check fails:

1. Do **not** proceed to step 6 (KB write). The briefing must NOT be persisted. 2. Write a status file with `status: "failed"` to `respond_to`. Include the violation list in `error`. 3. End the run.

D-25-28: Every briefing MUST contain causal hypothesis pattern + uncertainty pattern + valid confidence label. Failed self-check → no KB write.

6. Write briefing to KB

Run `node scripts/write-briefing.ts <projectId> <briefing-json-path>`. The script:

• Validates required fields (causal hypothesis, uncertainty, confidence)
• Calls `kb.writeBriefing()` with the briefing payload
• Emits `{ "briefing_id": "B-..." }` to stdout

The web tool picks up the new briefing via the `intelligence:briefing_ready` event.

7. Write status to outbox

Write a JSON status file to the path in the request's `respond_to` field:

{
  "request_id": "req_2026-05-02_1430_c8e1",
  "status": "complete",
  "briefing_id": "B-2026-0502-1430",
  "completed_at": "2026-05-02T14:31:42Z"
}

For triage_finding / dismiss_finding requests, the status payload may also carry `decision_id` if a recommendation was committed.

Failure paths

If you cannot produce a briefing meeting the verification criteria:

• Write a status with `"status": "failed"` and an explanation in `error`.
• Do **not** produce a partial briefing. Half-briefings degrade dashboard trust.

If `timeout_hint_ms` is approaching (>80% elapsed) and you have not finished:

• Write a status with `"status": "failed"` and `"error": "timeout"`.

Critical constraints

• **Never return briefing conte