@igorlau/dotagents 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +71 -2
  3. package/THIRD_PARTY_NOTICES.md +73 -0
  4. package/content/rules/comments.md +13 -0
  5. package/content/rules/core.md +8 -0
  6. package/content/rules/ponytail.md +29 -0
  7. package/content/rules/ponytail.upstream.json +8 -0
  8. package/content/skills/code-review/SKILL.md +58 -0
  9. package/content/skills/commit/SKILL.md +77 -0
  10. package/content/skills/debug/SKILL.md +142 -0
  11. package/content/skills/debug/UPSTREAM.json +8 -0
  12. package/content/skills/debug/agents/openai.yaml +3 -0
  13. package/content/skills/debug/scripts/hitl-loop.template.sh +44 -0
  14. package/content/skills/docs-writing/SKILL.md +82 -0
  15. package/content/skills/docs-writing/references/formatting.md +150 -0
  16. package/content/skills/docs-writing/references/global-and-accessible.md +46 -0
  17. package/content/skills/docs-writing/references/word-list.md +112 -0
  18. package/content/skills/grill-me/SKILL.md +11 -0
  19. package/content/skills/grill-me/UPSTREAM.json +8 -0
  20. package/content/skills/grill-me/agents/openai.yaml +5 -0
  21. package/content/skills/grilling/SKILL.md +34 -0
  22. package/content/skills/grilling/UPSTREAM.json +8 -0
  23. package/content/skills/grilling/agents/openai.yaml +3 -0
  24. package/content/skills/handoff/SKILL.md +20 -0
  25. package/content/skills/handoff/UPSTREAM.json +8 -0
  26. package/content/skills/handoff/agents/openai.yaml +5 -0
  27. package/content/skills/plan/SKILL.md +58 -0
  28. package/content/skills/writing-for-agents/SKILL-MECHANICS.md +22 -0
  29. package/content/skills/writing-for-agents/SKILL.md +85 -0
  30. package/content/skills/writing-for-agents/UPSTREAM.json +8 -0
  31. package/content/skills/writing-for-agents/agents/openai.yaml +3 -0
  32. package/dist/apply.js +119 -0
  33. package/dist/blocks.js +28 -0
  34. package/dist/build-info.json +1 -0
  35. package/dist/catalog.js +50 -0
  36. package/dist/cli.js +80 -0
  37. package/dist/commands.js +181 -0
  38. package/dist/frontmatter.js +23 -0
  39. package/dist/git.js +7 -0
  40. package/dist/manifest.js +35 -0
  41. package/dist/paths.js +25 -0
  42. package/dist/targets.js +74 -0
  43. package/package.json +36 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 igorlau
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,72 @@
1
- # Temporary Holding Version
1
+ # dotagents
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ dotagents installs a curated set of skills and rules into Claude Code,
4
+ OpenAI Codex, and GitHub Copilot, so every project you work on gets the same
5
+ AI workflow.
6
+
7
+ ## Install
8
+
9
+ To install the skills and rules for all your projects, run the following
10
+ command:
11
+
12
+ ```bash
13
+ npx --yes @igorlau/dotagents install
14
+ ```
15
+
16
+ ## Use dotagents in a repository
17
+
18
+ The global install covers every project, including team repositories, and
19
+ writes nothing to them.
20
+
21
+ To share the skills and rules with collaborators in a repository that you
22
+ own, run the following command in the repository, and commit the new files:
23
+
24
+ ```bash
25
+ npx --yes @igorlau/dotagents init
26
+ ```
27
+
28
+ ## Commands
29
+
30
+ The following table summarizes the commands. For options, run
31
+ `dotagents --help`.
32
+
33
+ | Command | Description |
34
+ | ------- | ----------- |
35
+ | `install` | Install globally. |
36
+ | `init` | Install into the current repository for collaborators. |
37
+ | `update` | Apply the latest catalog to existing installs. |
38
+ | `uninstall` | Remove everything that dotagents installed. |
39
+ | `doctor` | Check installs for missing or modified files. |
40
+ | `list` | List the skills. |
41
+ | `self-update` | Run `update` with the latest release. |
42
+
43
+ dotagents doesn't overwrite files that you changed or that it didn't write.
44
+ To overwrite them, pass `--force`.
45
+
46
+ ## What's included
47
+
48
+ The always-on rules in [`content/rules/`](content/rules/) cover working
49
+ agreements, the smallest complete change from
50
+ [ponytail](https://github.com/DietrichGebert/ponytail), and code comments.
51
+
52
+ The following skills load when a task needs them:
53
+
54
+ | Skill | Purpose |
55
+ | ----- | ------- |
56
+ | `plan` | Plan a change as small, verifiable steps. |
57
+ | `code-review` | Review a diff for correctness bugs. |
58
+ | `commit` | Commit changes as small, logical commits. |
59
+ | `docs-writing` | Write docs in the Google developer documentation style. |
60
+ | `debug` | Diagnose hard bugs with a feedback loop. |
61
+ | `grill-me` | Start an interview that sharpens a plan. |
62
+ | `grilling` | Run the interview method behind `grill-me`. |
63
+ | `handoff` | Summarize a conversation for another agent. |
64
+ | `writing-for-agents` | Write skills, `AGENTS.md`, and `CLAUDE.md` files. |
65
+
66
+ ## More information
67
+
68
+ - [Design specification](SPEC.md)
69
+ - [Contributing guide](CONTRIBUTING.md): report problems and propose changes
70
+ through pull requests
71
+ - [Third-party notices](THIRD_PARTY_NOTICES.md)
72
+ - [License (MIT)](LICENSE)
@@ -0,0 +1,73 @@
1
+ # Third-party notices
2
+
3
+ dotagents includes content from the following projects.
4
+
5
+ ## mattpocock/skills
6
+
7
+ The `debug`, `grill-me`, `grilling`, `handoff`, and `writing-for-agents`
8
+ skills come from [mattpocock/skills](https://github.com/mattpocock/skills).
9
+ Each skill's `UPSTREAM.json` file records the source commit and any local
10
+ changes. The project is licensed under the MIT License:
11
+
12
+ ```text
13
+ MIT License
14
+
15
+ Copyright (c) 2026 Matt Pocock
16
+
17
+ Permission is hereby granted, free of charge, to any person obtaining a copy
18
+ of this software and associated documentation files (the "Software"), to deal
19
+ in the Software without restriction, including without limitation the rights
20
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
21
+ copies of the Software, and to permit persons to whom the Software is
22
+ furnished to do so, subject to the following conditions:
23
+
24
+ The above copyright notice and this permission notice shall be included in all
25
+ copies or substantial portions of the Software.
26
+
27
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
28
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
29
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
30
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
31
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
32
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
33
+ SOFTWARE.
34
+ ```
35
+
36
+ ## DietrichGebert/ponytail
37
+
38
+ The `ponytail` rules in `content/rules/ponytail.md` come from the `AGENTS.md`
39
+ file in [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail).
40
+ `content/rules/ponytail.upstream.json` records the source commit and local
41
+ changes. The project is licensed under the MIT License:
42
+
43
+ ```text
44
+ MIT License
45
+
46
+ Copyright (c) 2026 DietrichGebert
47
+
48
+ Permission is hereby granted, free of charge, to any person obtaining a copy
49
+ of this software and associated documentation files (the "Software"), to deal
50
+ in the Software without restriction, including without limitation the rights
51
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
52
+ copies of the Software, and to permit persons to whom the Software is
53
+ furnished to do so, subject to the following conditions:
54
+
55
+ The above copyright notice and this permission notice shall be included in all
56
+ copies or substantial portions of the Software.
57
+
58
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
59
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
60
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
61
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
62
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
63
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
64
+ SOFTWARE.
65
+ ```
66
+
67
+ ## Google developer documentation style guide
68
+
69
+ The `docs-writing` skill is adapted from the
70
+ [Google developer documentation style guide](https://developers.google.com/style)
71
+ by Google, licensed under the
72
+ [Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/).
73
+ The content was condensed, reorganized, and reworded for coding agents.
@@ -0,0 +1,13 @@
1
+ # Code comments
2
+
3
+ Apply these rules when you write, refactor, or review code:
4
+
5
+ - Comment the why that the code can't show: a constraint, a workaround with its issue link, a non-obvious trade-off, an invariant, or the source of copied code. Keep it to one line when you can.
6
+ - Let the code carry the what. When a comment would restate the code, improve a name or extract a function instead, and write no comment.
7
+ - Write comments for future readers of the code as it is. Change history, notes such as "added" or "now uses", and messages to the reviewer belong in the commit message or pull request.
8
+ - Delete code instead of commenting it out. Git keeps the history.
9
+ - Document public APIs in the language's doc-comment convention: purpose, contract, errors, and side effects, not the implementation.
10
+ - Explain regular expressions and complex algorithms with what they match or compute.
11
+ - When you change code, update every comment that the change makes inaccurate, and delete comments that no longer apply.
12
+ - When you review code, flag comments that restate the code, contradict it, or narrate changes, and ask for a why comment where intentional code looks wrong.
13
+ - Match the comment density and style of the surrounding code.
@@ -0,0 +1,8 @@
1
+ # Working agreements
2
+
3
+ - Repository conventions come first. Before you implement or review anything, read the repository's agent instructions, project skills, `CONTRIBUTING.md`, style guides, and linter and formatter configuration, and study the surrounding code. Where they differ from these rules or a skill, follow the repository and point out the difference. Never change a repository's standards to match these rules.
4
+ - Verify before you report work as done: run the relevant tests, type checker, linter, or build, and show the result. If you couldn't verify something, say what and why.
5
+ - Report unrelated problems you notice instead of fixing them.
6
+ - Confirm with the user before destructive or hard-to-reverse actions: deleting files or branches, rewriting Git history, force pushing, changing data or schemas, and publishing or deploying anything.
7
+ - Look up facts yourself in the code, docs, configuration, and command output. Ask the user only for decisions and for facts you can't reach.
8
+ - Write commit messages in the repository's commit convention, or in Conventional Commits when it defines none. The commit belongs to the user alone: leave out `Co-Authored-By` trailers and AI attribution lines, even when tool defaults add them, and keep the trailers that the repository requires, such as `Signed-off-by`.
@@ -0,0 +1,29 @@
1
+ # Ponytail, lazy senior dev mode
2
+
3
+ You are a lazy senior developer. The best code is the code never written. You solve the whole problem with the least new code. End your reply with one or two lines: what you skipped or did not check, and any risk the user must know.
4
+
5
+ ## Before you write
6
+
7
+ Read the task and the code it touches. List every place your change must reach: callers, tests, fixtures, config, exports. Check what your change could break for users: data it would destroy or expose, callers that stop working. That is scope. Extra features are not.
8
+
9
+ ## The smallest complete change
10
+
11
+ Take the first option that fully works:
12
+
13
+ 1. Does it need to exist? Skip features, options and flexibility nobody asked for, and name them in one line. A vague request ("build me X") gets the smallest version that does the core job.
14
+ 2. Already in this codebase (a helper, component, service, pattern)? Use it the way the surrounding code does.
15
+ 3. Standard library or a platform feature? Use it, unless the project has its own. A house component beats a native widget.
16
+ 4. An installed dependency? Use it. Never add a dependency for a few lines.
17
+ 5. Can it be one line a reader gets at a glance? One line.
18
+ 6. Otherwise: the minimum code that works.
19
+
20
+ - Be lazy about the solution, never about the change itself: finish every part the task needs, including the callers, tests and fixtures your change breaks.
21
+ - No abstraction, wrapper, type conversion, option, config, boilerplate or "for later" code nobody asked for. Keep values in the form the platform already gives you. Deletion beats addition. Keep the structure the codebase already has: its layers, interfaces and conventions.
22
+ - The shortest working diff wins, once you know everything it must touch. A one-liner that needs decoding is not short.
23
+ - Bug fix: before you edit, grep every caller of the function you touch, then fix the root cause once in the shared code.
24
+ - Code you move or merge keeps its error handling and validation.
25
+ - Between options of equal size, take the one that is correct on edge cases.
26
+ - Lazy code without its check is unfinished: new non-trivial logic (a branch, a loop, a parser, money or security, or a whole new script or app) leaves one small test or an assert-based self-check. Trivial changes need none.
27
+ - A shortcut with a known limit gets a code comment in this form: `shortcut: <the limit>, <when to upgrade>`.
28
+
29
+ Never cut: validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs, anything the user asked for.
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/DietrichGebert/ponytail",
3
+ "path": "AGENTS.md",
4
+ "commit": "2961b52fc1fe6a5a87c7a959a79512e5c2f3ffe5",
5
+ "license": "MIT",
6
+ "modified": true,
7
+ "notes": "Removed the comment bullet (rules/comments.md owns comment guidance) and the closing note about the ponytail repository."
8
+ }
@@ -0,0 +1,58 @@
1
+ ---
2
+ name: code-review
3
+ description: Review a diff for correctness bugs. Use when the user asks to review code, a commit, a branch, or a pull request, or before committing a non-trivial change.
4
+ ---
5
+
6
+ # Code review
7
+
8
+ Find the defects that would make this change behave wrongly in production. Each finding is a **failure scenario**: concrete inputs or state that lead to a wrong result, a crash, or data loss.
9
+
10
+ ## Repository conventions first
11
+
12
+ Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the surrounding code. They take precedence over this skill: where they differ, follow the repository, and point out the difference instead of changing the repository's standard. Review against those standards. Code that follows a repository convention isn't a finding, even when general practice differs; code that breaks one is.
13
+
14
+ ## 1. Pick the target
15
+
16
+ Use the target the user named. Otherwise pick the first one that applies:
17
+
18
+ 1. A pull request number or URL: `gh pr diff <number>`.
19
+ 2. Staged and unstaged changes: `git diff HEAD`.
20
+ 3. The current branch against its base: `git diff $(git merge-base HEAD origin/main)`. Use the repository's default branch name.
21
+
22
+ State the target in one line before you start.
23
+
24
+ ## 2. Read for context
25
+
26
+ For each changed hunk, read the whole function, its callers, and the tests that cover it. Read the description of the pull request or linked issue if there is one, so you can check the change against its intent.
27
+
28
+ ## 3. Hunt
29
+
30
+ Check every hunk against each of these classes:
31
+
32
+ - **Logic**: inverted conditions, off-by-one errors, wrong operator, wrong variable, unreachable branches.
33
+ - **Edge cases**: empty, null, zero, negative, very large, Unicode, duplicate, and concurrent inputs.
34
+ - **Errors**: swallowed exceptions, missing cleanup, partial writes, retries that aren't idempotent.
35
+ - **Contracts**: changed signatures, return shapes, defaults, or API responses that existing callers depend on.
36
+ - **Data**: migrations that lose or lock data, missing transactions, inconsistent writes.
37
+ - **Security**: injection, missing authorization checks, secrets in code or logs, unsafe deserialization, path traversal.
38
+ - **Concurrency**: races, deadlocks, shared mutable state, ordering assumptions.
39
+ - **Tests**: changed behavior without a test that would fail if the change were wrong.
40
+
41
+ ## 4. Verify each finding
42
+
43
+ For each candidate, prove it: trace the code path with the failing input, or write and run a test that fails. Drop candidates you can't support with a concrete scenario, or report them as questions.
44
+
45
+ Report style issues only when they hide a bug or break a documented project convention.
46
+
47
+ ## 5. Report
48
+
49
+ List findings from most to least severe:
50
+
51
+ ```markdown
52
+ ### <severity: high | medium | low> <one-line summary>
53
+ `path/to/file.ts:42`
54
+ **Scenario:** <inputs or state> → <wrong result>
55
+ **Fix:** <smallest change that removes the defect>
56
+ ```
57
+
58
+ If you find nothing, say that the review found no defects, and list what you checked. Change code only when the user asks for fixes.
@@ -0,0 +1,77 @@
1
+ ---
2
+ name: commit
3
+ description: Commit changes as small, logical commits, with the user reviewing each one. Use when the user asks to commit, write a commit message, or split work into commits.
4
+ ---
5
+
6
+ # Commit
7
+
8
+ Each commit is **atomic**: one purpose, complete enough to build and pass tests, and small enough to review and revert on its own.
9
+
10
+ ## Repository conventions first
11
+
12
+ Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the surrounding code. They take precedence over this skill: where they differ, follow the repository, and point out the difference instead of changing the repository's standard. Follow the repository's commit convention when it defines one, in `CONTRIBUTING.md`, a commitlint or similar configuration, or a consistent history.
13
+
14
+ ## Review mode
15
+
16
+ Review is the default: the user approves the plan, and then each commit before you create it. When the user asks you to commit without review, for example "commit without asking", skip both approval stops for that request, and still show the summary in step 4.
17
+
18
+ ## 1. Inspect
19
+
20
+ Run `git status` and `git diff HEAD` to see every change, including untracked files. Note any changes that the user already staged, and ask whether they belong together. Run `git log -n 15 --oneline` to learn the convention and scopes that the repository uses.
21
+
22
+ ## 2. Propose the plan
23
+
24
+ Group the changes into commits by purpose: a refactor, a behavior change, a dependency update, and a formatting pass are separate commits. Keep a test in the same commit as the behavior it covers. Order the commits so that each one builds on the previous ones.
25
+
26
+ Check each file for secrets, credentials, local configuration, build output, and large binaries. Leave those out of the plan and tell the user.
27
+
28
+ Show the whole plan before you stage anything:
29
+
30
+ ```markdown
31
+ 1. `<message summary>`
32
+ - path/to/file.ts
33
+ - path/to/file.test.ts
34
+ 2. `<message summary>`
35
+ - path/to/other.ts (only the hunks for <purpose>)
36
+
37
+ Left out: <files and reasons, or none>
38
+ ```
39
+
40
+ Wait for the user's answer. When they ask to merge, split, reorder, or move files between commits, update the plan and show it again. Done when the user approves the plan.
41
+
42
+ ## 3. Commit each group
43
+
44
+ For each commit in the plan, in order:
45
+
46
+ 1. Stage only its changes with `git add -- <paths>`. When one file holds changes for two commits, write the hunks for this commit to a patch file and run `git apply --cached <patch>`.
47
+ 2. Show `git diff --staged --stat` and the full commit message.
48
+ 3. Wait for the user's answer:
49
+ - **Approve**: run `git commit`, and move to the next group.
50
+ - **Change**: adjust the staged files or the message, and show them again.
51
+ - **Skip**: run `git restore --staged -- <paths>`, and move to the next group.
52
+
53
+ Let pre-commit hooks run. When a hook fails, fix the cause, stage the fix, and show the commit again for approval. Amend an earlier commit only when the user asks.
54
+
55
+ ## 4. Summarize
56
+
57
+ Show `git log --oneline` for the commits you created, and list the changes that remain uncommitted. Push only when the user asks.
58
+
59
+ Done when every group in the plan is committed or skipped, and the user has seen the summary.
60
+
61
+ ## Message format
62
+
63
+ Use the repository's commit convention. When it defines none, use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format, and reuse the scopes you found in the log:
64
+
65
+ ```text
66
+ <type>(<optional scope>): <summary in the imperative mood>
67
+
68
+ <body: why the change is needed and what it affects, wrapped at 72 characters>
69
+
70
+ <footer: BREAKING CHANGE: ..., Refs: #123>
71
+ ```
72
+
73
+ - **type**: `feat`, `fix`, `refactor`, `perf`, `test`, `docs`, `build`, `ci`, or `chore`.
74
+ - **summary**: 50 characters or fewer when possible, 72 at most, without a final period.
75
+ - **body**: explain the reason and the effects. The diff already shows the lines that changed.
76
+ - **breaking change**: add `!` after the type or scope, as in `feat(api)!:`, and describe the change in a `BREAKING CHANGE:` footer.
77
+ - **authorship**: the commit belongs to the user alone. Leave out `Co-Authored-By` trailers and AI attribution such as "Generated with" lines, even when tool defaults add them. Keep the trailers that the repository requires, such as `Signed-off-by`.
@@ -0,0 +1,142 @@
1
+ ---
2
+ name: debug
3
+ description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
4
+ ---
5
+
6
+ # Diagnosing Bugs
7
+
8
+ A discipline for hard bugs. Skip phases only when explicitly justified.
9
+
10
+ When exploring the codebase, read `GLOSSARY.md` (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
11
+
12
+ ## Repository conventions first
13
+
14
+ Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the surrounding code. They take precedence over this skill: where they differ, follow the repository, and point out the difference instead of changing the repository's standard. Build the feedback loop with the repository's own test framework, scripts, and tooling.
15
+
16
+ ## Redact
17
+
18
+ This skill has you show commands, outputs and captured artifacts. **Redact every secret first**: write `<REDACTED>` in its place. Build loops against env vars, so the credential stays in the environment rather than in what you show. Captured artifacts carry auth headers: quote only the lines that carry the signal.
19
+
20
+ If the redacted output is not enough to diagnose the bug, say so and ask the user.
21
+
22
+ ## Phase 1: Build a feedback loop
23
+
24
+ **This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug (one that goes red on _this_ bug), you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
25
+
26
+ Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
27
+
28
+ ### Ways to construct one, in roughly this order
29
+
30
+ 1. **Failing test** at whatever seam reaches the bug: unit, integration, e2e.
31
+ 2. **Curl / HTTP script** against a running dev server.
32
+ 3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
33
+ 4. **Headless browser script** (Playwright / Puppeteer) that drives the UI and asserts on DOM/console/network.
34
+ 5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
35
+ 6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
36
+ 7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
37
+ 8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
38
+ 9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
39
+ 10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
40
+
41
+ Build the right feedback loop, and the bug is 90% fixed.
42
+
43
+ ### Tighten the loop
44
+
45
+ Treat the loop as a product. Once you have _a_ loop, **tighten** it:
46
+
47
+ - Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
48
+ - Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
49
+ - Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
50
+
51
+ A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight, a debugging superpower.
52
+
53
+ ### Non-deterministic bugs
54
+
55
+ The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not, so keep raising the rate until it's debuggable.
56
+
57
+ ### When you genuinely cannot build a loop
58
+
59
+ Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a redacted captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
60
+
61
+ ### Completion criterion: a tight loop that goes red
62
+
63
+ Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** (a script path, a test invocation, a curl) that you have **already run at least once** (show the invocation and its output, redacted), and that is:
64
+
65
+ - [ ] **Red-capable**: it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring"; it must be able to _catch this specific bug_.
66
+ - [ ] **Deterministic**: same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
67
+ - [ ] **Fast**: seconds, not minutes.
68
+ - [ ] **Agent-runnable**: you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.
69
+
70
+ If you catch yourself reading code to build a theory before this command exists, **stop: jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.
71
+
72
+ ## Phase 2: Reproduce + minimise
73
+
74
+ Run the loop. Watch it go red as the bug appears.
75
+
76
+ Confirm:
77
+
78
+ - [ ] The loop produces the failure mode the **user** described, not a different failure that happens to be nearby. Wrong bug = wrong fix.
79
+ - [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
80
+ - [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
81
+
82
+ ### Minimise
83
+
84
+ Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut, and keep only what's load-bearing for the failure.
85
+
86
+ Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
87
+
88
+ Done when **every remaining element is load-bearing**: removing any one of them makes the loop go green.
89
+
90
+ Do not proceed until you have reproduced **and** minimised.
91
+
92
+ ## Phase 3: Hypothesise
93
+
94
+ Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
95
+
96
+ Each hypothesis must be **falsifiable**: state the prediction it makes.
97
+
98
+ > Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
99
+
100
+ If you cannot state the prediction, the hypothesis is a vibe: discard or sharpen it.
101
+
102
+ **Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it; proceed with your ranking if the user is AFK.
103
+
104
+ ## Phase 4: Instrument
105
+
106
+ Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
107
+
108
+ Tool preference:
109
+
110
+ 1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
111
+ 2. **Targeted logs** at the boundaries that distinguish hypotheses.
112
+ 3. Never "log everything and grep".
113
+
114
+ **Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
115
+
116
+ **Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
117
+
118
+ ## Phase 5: Fix + regression test
119
+
120
+ Write the regression test **before the fix**, but only if there is a **correct seam** for it.
121
+
122
+ A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
123
+
124
+ **If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
125
+
126
+ If a correct seam exists:
127
+
128
+ 1. Turn the minimised repro into a failing test at that seam.
129
+ 2. Watch it fail. If you forced the red by mutating code or a fixture, `diff` against a pristine copy to prove the mutation landed before you trust it.
130
+ 3. Apply the fix.
131
+ 4. Watch it pass.
132
+ 5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
133
+
134
+ ## Phase 6: Cleanup
135
+
136
+ Required before declaring done:
137
+
138
+ - [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
139
+ - [ ] Regression test passes (or absence of seam is documented)
140
+ - [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
141
+ - [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
142
+ - [ ] The hypothesis that turned out correct is stated in the commit / PR message, so the next debugger learns
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/mattpocock/skills",
3
+ "path": "skills/engineering/diagnosing-bugs",
4
+ "commit": "49dd158d1076134a641b33efb035946536778336",
5
+ "license": "MIT",
6
+ "modified": true,
7
+ "notes": "Renamed from diagnosing-bugs to debug (frontmatter name and display_name). Added a 'Repository conventions first' section."
8
+ }
@@ -0,0 +1,3 @@
1
+ interface:
2
+ display_name: "Debug"
3
+ short_description: "Diagnose hard bugs and regressions"
@@ -0,0 +1,44 @@
1
+ #!/usr/bin/env bash
2
+ # Human-in-the-loop reproduction loop.
3
+ # Copy this file, edit the steps below, and run it.
4
+ # The agent runs the script; the user follows prompts in their terminal.
5
+ #
6
+ # Usage:
7
+ # bash hitl-loop.template.sh
8
+ #
9
+ # Two helpers:
10
+ # step "<instruction>" → show instruction, wait for Enter
11
+ # capture VAR "<question>" → show question, read response into VAR
12
+ #
13
+ # At the end, captured values are printed as KEY=VALUE for the agent to parse.
14
+ #
15
+ # `capture` prints its value back to the terminal, where the agent reads it,
16
+ # so capture observations, and leave signing in to the user as a `step`.
17
+
18
+ set -euo pipefail
19
+
20
+ step() {
21
+ printf '\n>>> %s\n' "$1"
22
+ read -r -p " [Enter when done] " _
23
+ }
24
+
25
+ capture() {
26
+ local var="$1" question="$2" answer
27
+ printf '\n>>> %s\n' "$question"
28
+ read -r -p " > " answer
29
+ printf -v "$var" '%s' "$answer"
30
+ }
31
+
32
+ # --- edit below ---------------------------------------------------------
33
+
34
+ step "Open the app at http://localhost:3000 and sign in."
35
+
36
+ capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
37
+
38
+ capture ERROR_MSG "Paste the error message (or 'none'):"
39
+
40
+ # --- edit above ---------------------------------------------------------
41
+
42
+ printf '\n--- Captured ---\n'
43
+ printf 'ERRORED=%s\n' "$ERRORED"
44
+ printf 'ERROR_MSG=%s\n' "$ERROR_MSG"