nakane1chome/dev-record

Dev Record

Run the action specified by $ARGUMENTS (either setup or status).

Passive recording of agent activity during Claude Code sessions. Captures what was planned, what happened, what was decided, and where the agent deviated.

Note: This is a record-only skill — it stores raw data but does not compute trends or analysis. Consumers (other skills, scripts, or humans) interpret the records.

Auto-loaded hooks: Running setup registers hooks directly in the project's .claude/settings.json. No --plugin-dir flag required — hooks fire automatically for every session in the project.

Actions

setup

Initialize the current project for dev-record.

Run ./install.sh from this skill's directory.

The script:

1. Adds audit/ops_record/ to .gitignore
2. Appends agent self-reporting guidance to CLAUDE.md
3. Creates audit/ops_record/ and audit/dev_record/ directories
4. Installs audit/agent-report.sh helper for agent self-reporting
5. Registers hooks in .claude/settings.json — hooks fire automatically from this point on, no --plugin-dir needed

status

Report the current state of dev-record in the project.

1. Check .gitignore includes audit/ops_record/
2. Count .json summary files in audit/dev_record/ — report number of recorded sessions
3. Read the most recent .json summary file (by filename sort) and display it

---

Reference

What Gets Recorded

Primary records (captured automatically by hooks):

| Record | Hook Event | What it captures | |--------|------------|------------------| | Human input | UserPromptSubmit | Every user prompt verbatim | | Agent decisions | PreToolUse | Every tool call the agent attempts | | Decision outcomes | PostToolUse | Whether each tool call succeeded or was denied | | Plan snapshots | PostToolUse | Transcript path captured when agent exits plan mode | | Session boundaries | SessionEnd | Session summary with raw counts | | Hook-detected anomalies | PreToolUse / PostToolUse | stop_ignored, hallucinated_path, repeated_failure, regression_unlabelled (see Limitations below) | | Plan-vs-actual file diff | SessionEnd | unrecorded_deviation — files in plan but not touched, or files touched but not in plan (see Plan File Diff Detection) | | Token usage | SessionEnd | Per-session input/output/cache token totals extracted from Claude Code session log | | Estimated cost | SessionEnd | Computed from token counts and model pricing (labeled estimated_cost_usd) | | Context compactions | SessionEnd | When the context window was compressed — trigger type and pre-compaction token count |

Secondary metrics (derived from primary records — raw counts, not computed rates):

| Metric | Source | |--------|--------| | tool_attempts | Count of PreToolUse events | | tool_rejections | Count of tool calls denied by the user | | corrections | User prompts that immediately follow a tool rejection * | | user_prompts | Total human inputs in the session |

* corrections is estimated. May overcount after benign failures (e.g. a grep with no results) and undercount approach-level corrections where the developer redirects without a tool rejection.

Agent self-reported events (hooks cannot detect intent — the agent must self-report):

| Event | When to report | |-------|----------------| | plan_stated | Agent commits to an approach — especially when implementing from a design document or specification, where the plan emerges from reading rather than from formal plan mode | | plan_deviation | Agent makes a decision that differs from the committed plan | | declined_difficult | Agent declines work because it would be difficult | | ignored_prior_failure | Agent discovers a prior failure and chooses not to resolve it | | scope_creep | Agent performs work not requested and not part of the committed plan | | observation_misread_as_instruction | Agent acted on something stated as an observation as if it were a directive |

Limitation: Self-reporting is least reliable for the exact situations it's designed to capture. An agent that declines difficult work may rationalize it as "out of scope" rather than flag it. Treat self-reported events as a lower bound, not a complete record. The developer should review sessions and append additional agent_report entries for events the agent missed.

Hook detection limitations: Hook-detected anomaly events (stop_ignored, repeated_failure, regression_unlabelled) use tool_response.success = false to indicate a failed tool call. In practice, success = false means the user denied the tool call, not that the command exited with a non-zero status. These detectors therefore identify repeated permission denials, not execution failures. Stop-word matching (stop_ignored) uses a fixed word list and will produce false positives for prompts that use these words in a non-imperative context (e.g. "don't worry, proceed").

Session metrics limitations: Token usage, cost, and compaction data are extracted from Claude Code's native session log (~/.claude/projects/). If the session log is not accessible (e.g. different user, remote execution), these fields will be null in the summary. The estimated_cost_usd uses a hardcoded pricing table and may not reflect current or discounted rates. Compaction events record pre_tokens but not the post-compaction count (Claude Code does not log it).

Subagent tracking: Hook payloads do not include agent or subagent identity. Tool calls from subagents appear as normal events, indistinguishable from main-agent calls. Subagent attribution would require Claude Code to add agent context to hook payloads.

Plan File Diff Detection

When a plan snapshot exists for the session, the SessionEnd hook automatically compares the plan's file list against actual git changes. This catches structural deviations the agent failed to self-report.

How it works:

1. The ExitPlanMode hook (in record-tool-call.sh) saves the plan content to audit/plans/
2. At session end, finalize-session.sh parses the plan for a markdown file table (| File | Action |)
3. It runs git diff --name-only to get the files actually changed during the session
4. It compares the two lists and emits unrecorded_deviation events for:
   • Planned files not touched — files listed in the plan with action Create/Modify that have no corresponding git change
   • Unplanned files touched — files changed in git that don't appear in the plan's file table
5. These events appear in the session summary's agent_reports array and in the -events.jsonl artifact

Limitations:

• Only detects file-level structural deviations, not intent-based ones ("I used a different algorithm")
• Requires a plan snapshot (sessions without ExitPlanMode are not checked)
• File path matching is substring-based (plan may use relative paths like src/bus/bus.hpp while git uses full paths)
• Files in audit/, .claude/, and common non-source paths are excluded from the unplanned check

Retention

Dev-record produces two tiers of data, split across two directories:

| Tier | Directory | Contents | Retention | |------|-----------|----------|-----------| | Project artifacts | audit/dev_record/ | Session summaries (.json), extracted agent reports and plan snapshots (-events.jsonl) | Permanent — commit to version control | | Operational detail | audit/ops_record/ | Full event logs (.jsonl) — individual tool calls, tool results, user prompts | Gitignored — subject to retention policy |

Project artifacts are the agent equivalent of design decision records (DDRs) and task conversations in human-led projects. They capture why decisions were made and should live alongside project documentation.

Operational detail is equivalent to ephemeral communication (chat messages, verbal discussions). Useful for debugging and review but not first-order project records. The install action adds audit/ops_record/ to .gitignore.

Data Schema

Event log (operational) — one JSONL file per session at audit/ops_record/<timestamp>-<session-id>.jsonl (e.g. 20260216T143022Z-abc123.jsonl). The YYYYMMDDTHHMMSSZ prefix ensures chronological sorting.

{"timestamp": "ISO8601", "session_id": "str", "type": "user_prompt", "content": {"prompt": "..."}}
{"timestamp": "ISO8601", "session_id": "str", "type": "tool_call", "content": {"tool": "Edit", "input": {}}}
{"timestamp": "ISO8601", "session_id": "str", "type": "tool_result", "content": {"tool": "Edit", "success": true}}
{"timestamp": "ISO8601", "session_id": "str", "type": "plan_snapshot", "content": {"transcript_path": "..."}}
{"timestamp": "ISO8601", "session_id": "str", "type": "agent_report", "content": {"event": "plan_stated", "detail": "..."}}
{"timestamp": "ISO8601", "session_id": "str", "type": "agent_report", "content": {"event": "plan_deviation", "detail": "..."}}
{"timestamp": "ISO8601", "session_id": "str", "type": "compaction", "content": {"trigger": "auto", "pre_tokens": 167238}}

Session summary (project artifact) — written at session end to audit/dev_record/<timestamp>-<session-id>.json.

Extracted events (project artifact) — agent reports, plan snapshots, and compaction events extracted to audit/dev_record/<timestamp>-<session-id>-events.jsonl. Only created if the session contains any of these event types.

{
  "session_id": "string",
  "started": "ISO8601",
  "ended": "ISO8601",
  "tool_attempts": 0,
  "tool_rejections": 0,
  "corrections": 0,
  "user_prompts": 0,
  "agent_reports": [],
  "plan_snapshots": 0,
  "model": "claude-opus-4-6",
  "token_usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  },
  "estimated_cost_usd": 0.0,
  "compactions": {
    "count": 0,
    "events": [{"timestamp": "ISO8601", "trigger": "auto", "pre_tokens": 0}]
  }
}

CLAUDE.md Snippet

The install action appends the following to the project's CLAUDE.md. This instructs the agent to self-report events that hooks cannot detect. The key design principle is log BEFORE proceeding — anchoring the reporting requirement to the decision point rather than relying on the agent remembering to report after the fact.

## Dev Record — Agent Self-Reporting

You MUST log self-report events using the helper script. These events are
extracted to `audit/dev_record/` at session end as permanent project artifacts.
Failure to report is itself a deviation.

**When to report — log BEFORE proceeding, not after:**

- **Plan stated**: You commit to an approach. Log BEFORE you start implementing.
- **Plan deviation**: You decide to skip, change, or add a step. Log BEFORE making the change.
- **Declined as difficult**: You decline work because it would be difficult.
- **Ignored prior failure**: You discover a prior failure and choose not to resolve it.
- **Scope creep**: You perform work not requested and not part of the committed plan.
- **Observation misread as instruction**: You acted on something stated as observation as if it were a directive.

**How to report:**

​```bash
bash audit/agent-report.sh "SESSION_ID" "EVENT_TYPE" "brief description"
​```

Where EVENT_TYPE is one of: `plan_stated`, `plan_deviation`, `declined_difficult`, `ignored_prior_failure`, `scope_creep`, `observation_misread_as_instruction`

**Decision-point triggers** — if you are about to do any of these, FIRST log a `plan_deviation`:
- Skip a file listed in the plan
- Create a file not listed in the plan
- Use a different approach than what the plan describes
- Change the interface or API from what was planned

Hook Scripts

Scripts live in hooks/ within this plugin directory. When loaded via --plugin-dir, Claude Code resolves ${CLAUDE_PLUGIN_ROOT}/hooks/ to find them — no copying into the project required.

| Script | Hook Event | Purpose | |--------|------------|---------| | record-prompt.sh | UserPromptSubmit | Log human input | | record-tool-call.sh | PreToolUse | Log agent tool decisions | | record-tool-result.sh | PostToolUse | Log outcomes, detect plan exits | | finalize-session.sh | SessionEnd | Extract project artifacts from ops_record to dev_record; plan-vs-actual file diff; session metrics extraction | | extract-session-metrics.sh | (called by finalize) | Read Claude session log for token usage, cost estimate, compaction events |

All scripts require jq. Each script exits 0 (non-blocking) and appends to JSONL, so concurrent sessions write to separate files without conflict.

Hook paths are resolved at install time and written as absolute paths in .claude/settings.json. If you move the plugin directory, re-run setup to update the paths.

When to Use This vs Other Tools

| Goal | Use | |------|-----| | Record raw session data (plans, input, decisions) | dev-record | | Track token usage and estimated cost per session | dev-record (extracted from Claude session logs) | | Visual session replay with token attribution | claude-devtools (complementary — reads ~/.claude/ logs directly) | | Analyze trends and measure agent improvement | A project-specific retrospective skill consuming dev-record data | | Review a document for quality | review-steps, strong-edit |