// Run or continue a differential debugging session between two implementations, traces, captures, or outputs. Record artifact identity, exact commands, first mismatch progression, findings, validation, and next probe in a durable session log.
| name | differential-session-runner |
| description | Run or continue a differential debugging session between two implementations, traces, captures, or outputs. Record artifact identity, exact commands, first mismatch progression, findings, validation, and next probe in a durable session log. |
| writes-to | memory-bank/evidence/ |
| allowed-tools | ["Read","Write","Edit","Bash"] |
| hard-guards | ["Record exact commands, artifact paths, and hashes whenever available","Prefer continuing an existing session for the same artifact identity instead of creating duplicates","Do not claim a mismatch is fixed without validation evidence","Keep prior findings intact; append or mark superseded findings explicitly"] |
Use this skill when debugging requires a durable evidence trail rather than ad hoc notes.
This skill is for workflows where you are comparing:
The goal is not only to investigate. The goal is to leave behind a session artifact another operator or agent can continue.
Use this skill when the user asks to:
Every differential investigation should produce a reusable evidence packet.
A good session artifact lets another operator answer:
If the repo already has a native evidence location, use it.
Examples:
docs/.../sessions/docs/chunks/analysis/.../reports/If the repo does not already have a native convention, write to:
memory-bank/evidence/YYYY-MM-DD_HH-MM-SS_<topic>-session.mdmemory-bank/evidence/index.mdBefore creating anything, search for:
Read the relevant guidance and continue the repo's existing pattern.
Capture the strongest available identity for the artifact:
If a content hash is possible, record it early and use it as the main session identity.
Search existing sessions for the artifact identity.
Capture the exact commands used for the first comparison step.
Examples:
python compare.py --baseline out/a.json --candidate out/b.json
pytest tests/test_replay.py -k case_17
mytool diff trace_a.cdt trace_b.cdt
Never summarize commands loosely. Record them exactly.
Capture the first relevant divergence and, if applicable, how it moved over time.
Examples:
If later fixes move the mismatch frontier, append the new progression rather than deleting the old one.
Write findings as evidence-backed observations, not guesses.
Good findings:
If code changes are made during the investigation, capture them in a separate section:
If no changes were made, state that explicitly.
List the validation commands and their results.
Examples:
Do not write "fixed" without a validation section.
Every session should end with one of:
---
title: "<topic> – Differential Session"
phase: Evidence
date: "YYYY-MM-DD HH:MM:SS"
owner: "<agent_or_user>"
tags: [evidence, differential, <topic>]
---
## Artifact
- Path: `<path>`
- Identity: `<sha256|commit|case-id>`
## Baseline Commands
- `<exact command 1>`
- `<exact command 2>`
## First Mismatch Progression
- baseline: `<first mismatch>`
- after fix 1: `<new frontier>`
- after fix 2: `<cleared|new mismatch>`
## Key Findings
- finding 1
- finding 2
## Landed Changes
- `path/to/file` → change summary
- `tests/...` → validation coverage added
## Validation
- `<command>` → `<result>`
- `<command>` → `<result>`
## Outcome / Next Probe
- `<cleared | next probe | blocked reason>`
A completed session artifact should make handoff possible with no hidden context.
It must include:
After updating the session artifact:
plan-phaseexecute-phaseExecute implementation plans from .artifacts/plan/. Focus on EXECUTING ONLY - no planning, no fixes outside plan scope. Uses gated checks, atomic commits, and maintains a single execution log in .artifacts/execute/. Use when the user says "execute this plan" or provides a plan path.
Map a repository's mechanical harness layers: canonical check command, local and CI gates, architecture boundaries, structural rules, behavioral verification, docs ratchets, evidence workflows, and operator-facing surfaces. Use when you need to understand how a repo keeps change safe.
Generate execution-ready implementation plans from research docs - planning ONLY, no fixing or verifying. North Star is whether a JR developer can execute the plan with zero additional context.
Perform quality assurance on code changes after the research-phase -> plan-phase -> execute-phase workflow. STRICTLY QA only—no coding, no fixes, no source-code changes. Focus on changed areas only, emphasizing control/data flow correctness.
This skill should be used when mapping or researching a codebase to understand its structure, patterns, and architecture. Use when the user asks to "map the codebase", "research how X works", "find all Y patterns", or needs to understand code organization. Produces factual structural maps in .artifacts/research/—no suggestions, no recommendations, just what exists. Uses ast-grep for structural pattern matching.
This skill should be used when creating, refreshing, or validating a repository `AGENTS.md` so it stays concise, current, and grounded in repository evidence. Use when `AGENTS.md` is missing or stale, after refactors or tooling changes, when new docs become the system of record, or when adding lightweight drift checks.