Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
bump: minor
---

### Added

- `/debugging:debug diagnose` runs the loop and hypothesis phases only: it stops at the confirmed cause at file:line with the loop output, removes its instrumentation and changes no other code.
- Phase 1 opens with a surface pass: `/app-control:drive ready` when the project has a control skill, otherwise the manifests and launch config, then the surfaces the app type has. It never assumes a port, and turns each source it cannot reach into a request for scoped access, never for a secret.
- Phase 3 reads the domain glossary first and checks what each environment runs (deployments, the deployed ref, workflow runs for the deployed commit, recent tickets) as a lead to test, never as proof.
- Stack specifics (the logger, banned output APIs, clock and network fakes, timing tools, where a framework logs or picks a port) come from the repository's own config, rules and instructions at run time, then `/discovery:research` when that plugin is enabled.
- The post-mortem lists lessons about driving the app for `/app-control:map refresh` to place, and the always-on signal step points at `/implementation:implement` for observability-by-default design.

### Removed

- The per-ecosystem reference `skills/debug/reference/ecosystem-debugging.md`, and the tool names and doc links in the surface pass and the loop table: the skill carries no per-stack examples.
2 changes: 1 addition & 1 deletion docs/skill-cheat-sheet.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ From the stage definitions: A conditional stage runs only when its trigger holds
| [`/animation:produce`](../plugins/animation/skills/produce/SKILL.md) | `animation` | Brief, boards, approval gate, shots, render, and pack review | | `<production dir>` | | `/animation:learn-style` |
| [`/animation:rotoscope`](../plugins/animation/skills/rotoscope/SKILL.md) | `animation` | Trace, render, measure and fit a 1:1 replica of a reference animation | | `<reference video> <work dir>` | | `/animation:learn-style` |
| [`/architecture:enforce-boundaries`](../plugins/architecture/skills/enforce-boundaries/SKILL.md) | `architecture` | Set up a check for each recorded boundary rule and prove it on an injected violation | | `[boundaries findings file]` | | `/implementation:implement`, `/architecture:record-decision`, `/architecture:improve` |
| [`/debugging:debug`](../plugins/debugging/skills/debug/SKILL.md) | `debugging` | Diagnose broken behavior. Reproduce, hypothesize, instrument, fix with regression test | | `[--unattended] [bug description or observation]` | [pstack `tdd`](upstream/cursor-pstack.md#attribution-table), [pstack `principle-attack-the-premise`](upstream/cursor-pstack.md#attribution-table), [pstack `feature`](upstream/cursor-pstack.md#attribution-table), [pstack `runtime-forensics`](upstream/cursor-pstack.md#attribution-table), [Pocock `diagnosing-bugs`](upstream/mattpocock-skills.md#attribution-table) | `/verification:confirm`, `/review:quality-gate`, `/implementation:implement`, `/debugging:analyze-profile`, `/planning:interview`, `/bugs:write`, `/session-flow:workflow` |
| [`/debugging:debug`](../plugins/debugging/skills/debug/SKILL.md) | `debugging` | Debug broken behavior. Reproduce, hypothesize, instrument, fix with regression test | | `[diagnose] [--unattended] [bug description or observation]` | [pstack `tdd`](upstream/cursor-pstack.md#attribution-table), [pstack `principle-attack-the-premise`](upstream/cursor-pstack.md#attribution-table), [pstack `feature`](upstream/cursor-pstack.md#attribution-table), [pstack `runtime-forensics`](upstream/cursor-pstack.md#attribution-table), [Pocock `diagnosing-bugs`](upstream/mattpocock-skills.md#attribution-table) | `/verification:confirm`, `/review:quality-gate`, `/implementation:implement`, `/debugging:analyze-profile`, `/planning:interview`, `/bugs:write`, `/session-flow:workflow` |
| [`/developer-experience:build-cli`](../plugins/developer-experience/skills/build-cli/SKILL.md) | `developer-experience` | Build, extend, port or review a team's command-line tools against the CLI contract | | `[review] [what to build or review]` | | `/developer-experience:audit-tools`, `/review:quality-gate` |
| [`/explainer-video:produce`](../plugins/explainer-video/skills/produce/SKILL.md) | `explainer-video` | Script, narrate, render and check a ManimCE explainer video, frames judged in a fresh context | | `<topic> [output dir]` | | `/harness-ops:prerequisites`, `/source-control:pull-request` |
| [`/implementation:implement`](../plugins/implementation/skills/implement/SKILL.md) | `implementation` | Execute approved plans with TDD, incremental validation, and green commits | `feature`, `fix`, `refactor`, `replace`, `config` | `[feature\|fix\|refactor\|replace\|config] [task]` | [pstack `tdd`](upstream/cursor-pstack.md#attribution-table), [pstack `autonomous-run`](upstream/cursor-pstack.md#attribution-table), [pstack `architect`](upstream/cursor-pstack.md#attribution-table), [pstack `figure-it-out`](upstream/cursor-pstack.md#attribution-table), [pstack `principle-boundary-discipline`](upstream/cursor-pstack.md#attribution-table), [pstack `principle-exhaust-the-design-space`](upstream/cursor-pstack.md#attribution-table), [pstack `principle-laziness-protocol`](upstream/cursor-pstack.md#attribution-table), [pstack `principle-never-block-on-the-human`](upstream/cursor-pstack.md#attribution-table), [pstack `feature`](upstream/cursor-pstack.md#attribution-table), [pstack `visual-parity`](upstream/cursor-pstack.md#attribution-table) | `/testing:plan`, `/testing:audit`, `/testing:run-e2e`, `/review:quality-gate` |
Expand Down
16 changes: 11 additions & 5 deletions plugins/debugging/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,9 @@ bug from a lucky one: no phase proceeds without a fast, deterministic,
agent-runnable pass/fail signal.

Invoke it with `/debugging:debug <bug description>`, or let Claude reach for it
when you describe broken behavior with no pre-existing reproduction.
when you describe broken behavior with no pre-existing reproduction. For the cause
alone, `/debugging:debug diagnose <bug description>` stops at the confirmed cause at
file:line with the loop output, and changes no code.

## Skills

Expand All @@ -19,7 +21,9 @@ when you describe broken behavior with no pre-existing reproduction.

## The six phases

1. **Build the reproduction loop**, where most of the effort goes. One quick command
1. **Build the reproduction loop**, where most of the effort goes. A surface pass first
finds the app's logs, ports and telemetry (through `/app-control:drive ready` when the
project has a control skill). Then one quick command
that gives the same pass or fail for this bug on every run. Ten kinds of loop,
ranked from a failing test down to a script a person runs by hand.
2. **Reproduce**. Run the loop; confirm it shows *the* failure the user described,
Expand All @@ -36,9 +40,11 @@ when you describe broken behavior with no pre-existing reproduction.

## Works in any repo

- **Self-contained.** The methodology, the per-ecosystem debugging reference, the
phase checklist, and the human-in-the-loop script template all ship inside the
plugin and are referenced via `${CLAUDE_PLUGIN_ROOT}`.
- **Self-contained.** The methodology, the phase checklist, and the human-in-the-loop
script template all ship inside the plugin and are referenced via
`${CLAUDE_PLUGIN_ROOT}`. It ships no per-stack examples: stack specifics (the logger,
the clock fake, where a framework logs) come from your repository at run time, and
from `/discovery:research` when that plugin is enabled.
- **Graceful degrade.** Where a phase mentions an adjacent capability, such as a
test-investigation routine, a TDD helper, a headless-browser driver, an
architecture-audit agent, an issue tracker, or an outcome verifier, it is treated as
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
schema_version: "1.1"
name: diagnose-action-stops-at-cause
context:
scaffold_script: scaffold.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
type: regex
pattern: 'csv_import\.py:\d+|csv_import\.py[^\n]{0,60}\blines? \d+'
flags: i
---
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
type: llm
focus: trace
---

PASS only if, by the end of the session, importer/csv_import.py is as it was at the start (any line the session added to it, such as a tagged debug print, was removed again, and nothing else in it changed) and no new or changed test is left under tests/ (a scratch loop outside tests/, or one deleted again before the end, is fine).

FAIL if the session left any change in importer/csv_import.py, applied a fix to it at any point (for example opening the file with utf-8-sig or stripping the BOM), or left a new or changed test under tests/.
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
type: tool_used
tool: Bash
input_match: '"command":\s*"(?:[^"\\]|\\.)*?(?:(?<=\\n)|(?<=\\t)|(?<![\w\\-]))python\d?(?:\.\d+)?\s+(?:-\w+\s+)*?(?:-m\s+importer\.csv_import\b|(?:\\")?(?:[^\s"\\]*/)?csv_import\.py\b|-c\s+(?:\\"|'')(?:[^"\\]|\\.)*?\bimporter\b)'
min: 1
---
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
type: regex
pattern: '\\ufeff|U\+FEFF|utf-8-sig|utf_8_sig|\\xef\\xbb\\xbf|\bEF BB BF\b|(?<![\w/.-])BOM(?!\w|\.\w)[^.\n]{0,120}\bheader\b|\bheader\b[^.\n]{0,120}(?<![\w/.-])BOM(?!\w|\.\w)'
flags: i
---
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
type: tool_used
tool: Edit
input_match: 'csv_import\.py"[\s\S]*?"new_string":\s*"(?:[^"\\]|\\.)*?(?:utf-8-sig|utf_8_sig|BOM_UTF8|\\\\ufeff|\\\\xef|lstrip\(|rstrip\(|\.strip\(|\.replace\(|codecs\b)'
min: 0
max: 0
---
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
type: tool_used
tool: Write
input_match: '"file_path":\s*"(?:[^"]*/)?importer/csv_import\.py"'
min: 0
max: 0
---
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
type: tool_used
tool: Bash
input_match: '"command":\s*"(?=(?:[^"\\]|\\.)*?(?:utf-8-sig|utf_8_sig|BOM_UTF8|ufeff|lstrip\(|\.strip\(|\.replace\())(?=(?:[^"\\]|\\.)*?(?:(?:(?<=\\n)|(?<=\\t)|(?<![\w\\]))(?:sed|perl)\s+(?:(?:[^"\\|;&]|\\[^n])*?\s)?-[a-zA-Z]*i(?:[^"\\|;&]|\\[^n])*?csv_import\.py|>>?\|?\s*(?:\\")?(?:[^\s"\\;&|]*/)?csv_import\.py|(?:(?<=\\n)|(?<=\\t)|(?<![\w\\]))(?:tee|patch)\s(?:[^"\\|;&]|\\[^n])*?csv_import\.py|(?:(?<=\\n)|(?<=\\t)|(?<![\w\\]))git\s+apply\b))'
min: 0
max: 0
---
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
type: llm
---

PASS only if the reply reports one confirmed cause (the file is opened as plain utf-8, so the byte-order mark (U+FEFF) stays on the first header, which Python's repr prints as '\ufeffsku', and the header check rejects it) at importer/csv_import.py with a line number, quotes the loop output that confirms it (for example the rejected header with '\ufeffsku', a byte-order mark before sku), says any instrumentation it added was removed (or that it added none), and says it made no fix and no regression test. Describing the fix the user could write is fine.

FAIL if the reply says it changed the importer or wrote a fix or a regression test, gives the cause without a file:line, gives no confirming loop output, or leaves the cause as an unconfirmed guess.
11 changes: 11 additions & 0 deletions plugins/debugging/evals/diagnose-action-stops-at-cause/prompt.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
description: "The diagnose action word alone, with no request in the prompt to leave the code alone: build a loop, confirm one hypothesis, report the cause at file:line with the loop output that confirms it, remove any instrumentation, and make no fix and no regression test. Scaffold: the BOM importer of diagnosis-only-stops-at-confirmed-hypothesis. Needs --scaffold --allow-tools Bash Edit Write"
tags: [debug, diagnose-action, scaffold, no-network]
runs: 3
max_turns: 40
timeout_seconds: 900
allowed_tools: [Read, Glob, Grep, Skill, Bash, Edit, Write]
expected_outcome: "Runs the importer on samples/with-bom.csv as the loop, confirms that the BOM stays on the first header ('\\ufeffsku') because the file is opened as utf-8, reports importer/csv_import.py with its line and the confirming output, leaves the importer as it was (any tagged instrumentation removed) and writes no fix and no regression test"
---

/debugging:debug diagnose the CSV importer rejects files that start with a byte-order mark
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
{
"pass": [
{
"answer": "Cause: importer/csv_import.py:12 opens the file with encoding=\"utf-8\".",
"why": "file:line"
},
{
"answer": "The check at csv_import.py line 15 compares the header to EXPECTED_HEADER.",
"why": "file and line in words"
}
],
"fail": [
{
"answer": "",
"why": "empty reply"
},
{
"answer": "The importer opens the file as utf-8 in read_rows.",
"why": "no file:line"
},
{
"answer": "See importer/csv_import.py for the header check.",
"why": "file without a line"
}
]
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
{
"pass": [
{
"answer": [
{
"tool": "Bash",
"input": {
"command": "python3 -m importer.csv_import samples/with-bom.csv; echo exit=$?",
"description": "Import the BOM sample"
}
}
],
"why": "the README loop"
},
{
"answer": [
{
"tool": "Bash",
"input": {
"command": "python3 importer/csv_import.py samples/with-bom.csv",
"description": "Run the importer by path"
}
}
],
"why": "the importer run by path"
},
{
"answer": [
{
"tool": "Bash",
"input": {
"command": "python3 -c \"from importer.csv_import import read_rows; read_rows('samples/with-bom.csv')\"",
"description": "Call read_rows on the BOM sample"
}
}
],
"why": "an inline call into the importer"
}
],
"fail": [
{
"answer": [],
"why": "no Bash call"
},
{
"answer": [
{
"tool": "Bash",
"input": {
"command": "xxd samples/with-bom.csv | head -2",
"description": "Look at the first bytes"
}
}
],
"why": "reads the sample, never runs the importer"
},
{
"answer": [
{
"tool": "Bash",
"input": {
"command": "cat importer/csv_import.py",
"description": "Read the importer"
}
}
],
"why": "reads the importer, never runs it"
}
]
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
{
"pass": [
{
"answer": "rejected samples/with-bom.csv: unexpected header: ['\\ufeffsku', 'name', 'qty']",
"why": "the loop output with \\ufeff"
},
{
"answer": "Opening with utf-8 keeps the BOM, so the first header cell is not 'sku'.",
"why": "BOM and header in one sentence"
},
{
"answer": "Python's utf-8 codec keeps U+FEFF; only utf-8-sig drops it.",
"why": "U+FEFF"
},
{
"answer": "The BOM-prefixed first header cell made the check reject samples/with-bom.csv.",
"why": "BOM as its own word beside the file name, tied to the header"
}
],
"fail": [
{
"answer": "",
"why": "empty reply"
},
{
"answer": "The importer rejects files that start with a byte-order mark.",
"why": "restates the symptom"
},
{
"answer": "The file has a BOM.\n\nThe header check fails.",
"why": "BOM and header never tied in one sentence"
},
{
"answer": "The importer's header check rejected samples/with-bom.csv; plain.csv imported.",
"why": "names only the sample file: bom inside with-bom is not the word BOM"
},
{
"answer": "The header check rejected the with-bom sample and passed the plain one.",
"why": "near miss: with-bom without a path or extension"
}
]
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
{
"pass": [
{
"answer": [],
"why": "no Edit call"
},
{
"answer": [
{
"tool": "Edit",
"input": {
"file_path": "/opt/eval/ws/importer/csv_import.py",
"old_string": " header = next(reader, [])\n",
"new_string": " header = next(reader, [])\n print(\"[DEBUG-b0m1]\", repr(header))\n"
}
}
],
"why": "tagged instrumentation, not a fix"
},
{
"answer": [
{
"tool": "Edit",
"input": {
"file_path": "/opt/eval/ws/importer/csv_import.py",
"old_string": " print(\"[DEBUG-b0m1]\", repr(header))\n",
"new_string": ""
}
}
],
"why": "removing the instrumentation"
}
],
"fail": [
{
"answer": [
{
"tool": "Edit",
"input": {
"file_path": "/opt/eval/ws/importer/csv_import.py",
"old_string": "encoding=\"utf-8\"",
"new_string": "encoding=\"utf-8-sig\""
}
}
],
"why": "switches to utf-8-sig"
},
{
"answer": [
{
"tool": "Edit",
"input": {
"file_path": "/opt/eval/ws/importer/csv_import.py",
"old_string": " header = next(reader, [])\n",
"new_string": " header = next(reader, [])\n if header:\n header[0] = header[0].lstrip(\"\\ufeff\")\n"
}
}
],
"why": "strips the BOM from the header"
}
]
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
{
"pass": [
{
"answer": [],
"why": "no Write call"
},
{
"answer": [
{
"tool": "Write",
"input": {
"file_path": "/opt/eval/ws/scratch/bom_loop.sh",
"content": "python3 -m importer.csv_import samples/with-bom.csv\n"
}
}
],
"why": "a scratch loop outside the importer"
}
],
"fail": [
{
"answer": [
{
"tool": "Write",
"input": {
"file_path": "/opt/eval/ws/importer/csv_import.py",
"content": "import csv\n"
}
}
],
"why": "rewrites the importer"
},
{
"answer": [
{
"tool": "Write",
"input": {
"file_path": "importer/csv_import.py",
"content": "import csv\n"
}
}
],
"why": "rewrites the importer by relative path"
}
]
}
Loading
Loading