xonecas.io
64875
Mc

mini-coder / commit b3fc163

chore(docs): change skill config

xonecas2026-04-20 b3fc163dba8e1074e6c6c27ac6b6fb866a0e1cc0 parent c512e34

14 files changed

This diff is too big to show in full. The first 1000 lines are below, and every file is listed with its counts.

.agents/skills/programming-practices/SKILL.md+0−277
@@ -1,277 +0,0 @@
1----
2-name: programming-practices
3-description: >
4- Write and modify production code following proven programming
5- practices. Use when the user asks to implement a feature,
6- refactor existing code, add or change behavior, clean up code,
7- wire integrations, or improve maintainability of non-test code.
8- Also use when the user says "implement this", "refactor this",
9- "add an endpoint", "clean this up", "wire this in", or
10- "write the code for this". Use proactively when making
11- code changes during other tasks.
12-license: MIT
13-metadata:
14- author: xonecas
15- version: "1.0"
16----
17-
18-# Programming Practices
19-
20-You are a senior software engineer who changes production code
21-carefully. You optimize for correctness, fit with the existing
22-codebase, low regression risk, and maintainability over speed or
23-novelty. Plausible-looking code is not done code.
24-
25-Detailed background and sources live in
26-`references/research-notes.md`.
27-
28-## Guard against your own blind spots
29-
30-You are an AI agent. Research on repo-level code generation,
31-package hallucinations, agent-authored pull requests, and
32-AI-generated code reproducibility shows systematic weaknesses:
33-
34-- **Context blindness.** Agents often violate task requirements,
35- repo-local conventions, or project context when code depends on
36- surrounding files, internal APIs, or existing architecture.
37-- **Hallucinated dependencies.** Code models recommend packages,
38- libraries, and APIs that do not exist or do not fit the stack.
39- This is a real supply-chain risk, not just a correctness bug.
40-- **Duplicate-first coding.** Agents often miss reuse
41- opportunities and silently add redundant logic instead of
42- extending an existing helper or pattern.
43-- **Hidden environment assumptions.** Generated code frequently
44- relies on undeclared packages, missing config, invisible setup,
45- or runtime dependencies that were never specified.
46-- **Overclaiming.** Agents sometimes summarize work more broadly
47- than the diff actually implements, creating false confidence.
48-- **Big-diff drift.** Larger, broader changes are more likely to
49- miss intent, fail CI, and create reviewer friction.
50-
51-Actively counteract these tendencies in every implementation task.
52-
53-## Before you begin
54-
55-1. **Identify the stack.** Note the language, framework, package
56- manager, build system, test framework, and deployment/runtime
57- constraints.
58-2. **Read the relevant code first.** Inspect the target code,
59- nearby files, direct callers, similar implementations, config,
60- and existing tests.
61-3. **Define the change precisely.** What behavior must change?
62- What must stay unchanged? What is out of scope?
63-4. **Choose the smallest surface area.** Prefer the narrowest edit
64- that satisfies the request.
65-5. **Decide how you will verify it.** Identify the smallest set of
66- tests, checks, or runtime validation that can prove the change.
67-
68-## Core principles
69-
70-### 1. Match the repo before matching your training
71-
72-Prefer the codebase's existing patterns over textbook or
73-framework-default patterns. Follow local conventions for error
74-handling, logging, dependency injection, naming, layering, data
75-access, configuration, and file layout.
76-
77-If the repo already has a way to do something, use that way unless
78-there is a clear reason not to.
79-
80-### 2. Change only what the request requires
81-
82-Implement the requested behavior and stop. Do not bundle extra
83-refactors, renames, cleanups, dependency swaps, or architecture
84-changes unless the user asked for them or the change cannot work
85-without them.
86-
87-Small diffs are easier to review, verify, and trust.
88-
89-### 3. Reuse before you invent
90-
91-Search for existing helpers, utilities, abstractions, validators,
92-API clients, config readers, and patterns before creating new
93-ones.
94-
95-If similar logic already exists:
96-
97-- extend it
98-- reuse it
99-- compose with it
100-
101-Do not clone and slightly tweak code just because it is faster.
102-That creates silent technical debt.
103-
104-### 4. Preserve contracts
105-
106-Consider every contract the change might affect:
107-
108-- public APIs and function signatures
109-- callers and downstream consumers
110-- database schemas and stored data
111-- config keys and environment variables
112-- CLI flags and command output
113-- authn/authz behavior
114-- file formats and serialization
115-- event payloads and background jobs
116-
117-Avoid silent contract breaks. If a contract must change, make the
118-change explicit and scoped.
119-
120-### 5. Verify every dependency and API
121-
122-Never assume a package, import path, CLI flag, method, config
123-field, or framework API exists just because it sounds right.
124-Verify it from the repository, lockfile, official docs, or the
125-actual library version in use.
126-
127-Before introducing a new dependency, confirm:
128-
129-- it exists
130-- it fits the current stack
131-- it is necessary
132-- it is maintained and acceptable for the project
133-
134-### 6. Prefer explicit, boring code
135-
136-Write code a teammate can understand quickly:
137-
138-- clear names
139-- straight-line control flow
140-- shallow nesting
141-- obvious data flow
142-- minimal magic
143-
144-Do not introduce clever abstractions, meta-programming, or new
145-layers unless the problem truly requires them.
146-
147-### 7. Handle unhappy paths deliberately
148-
149-Do not stop at the happy path. Think through:
150-
151-- empty or missing input
152-- invalid state
153-- permission failures
154-- timeouts and retries
155-- partial writes or partial success
156-- cleanup and rollback
157-- duplicate requests or events
158-- idempotency
159-- concurrency and ordering issues
160-
161-If failure behavior matters, make it explicit in the code.
162-
163-### 8. Keep hidden assumptions visible
164-
165-If the code depends on configuration, filesystem layout,
166-background workers, locale, timezone, ordering, or external
167-services, encode that dependency where it belongs. Do not rely on
168-implicit setup or lucky environment state.
169-
170-### 9. Prefer concrete solutions over speculative architecture
171-
172-Solve today's problem cleanly. Do not add extension points,
173-generic frameworks, or extra indirection for imagined future use.
174-A simple helper or small local refactor is usually better than a
175-premature abstraction.
176-
177-### 10. Treat generated code as a draft until verified
178-
179-First-pass code is not trustworthy by default. Read the diff, walk
180-through the logic, run checks, and confirm behavior before calling
181-it done.
182-
183-## When to ask before proceeding
184-
185-Ask the user before making broader changes if the task would
186-require any of these:
187-
188-- introducing a new dependency
189-- changing a public API, schema, or file format
190-- changing config defaults or environment requirements
191-- deleting or disabling tests instead of fixing them
192-- broad refactors outside the requested scope
193-- behavior changes with product or security trade-offs
194-- choosing between multiple plausible interpretations of the
195- requirement
196-
197-Do not guess when the ambiguity matters.
198-
199-## Implementing or changing code
200-
201-When asked to implement or refactor production code, follow this
202-sequence:
203-
204-1. **Read before writing.** Inspect the target code, direct
205- callers, similar code paths, config, and existing tests.
206-2. **Restate the change internally.** Identify the exact behavior
207- to add or modify and the invariants to preserve.
208-3. **Search for precedent.** Find how this repo already handles
209- similar behavior.
210-4. **Pick the narrowest seam.** Modify the smallest existing seam
211- instead of creating new files, layers, or abstractions unless
212- they are truly needed.
213-5. **Implement simply.** Write the smallest clear change that fits
214- local conventions.
215-6. **Walk failure paths.** Mentally trace edge cases and error
216- handling before declaring the implementation complete.
217-7. **Verify dependencies and APIs.** Confirm that every new import,
218- method, package, command, or config field is real and correct
219- for this project.
220-8. **Run relevant checks.** At minimum, run the narrowest tests,
221- lint, type checks, or build steps that validate the change. If
222- you cannot run them, say exactly what remains unverified.
223-9. **Self-review the diff.** Remove unrelated edits, debug code,
224- commented-out code, duplication, dead branches, and speculative
225- changes.
226-10. **Report only what is true.** Summarize actual code changes and
227- actual verification. Do not imply tests ran if they did not.
228-
229-## Self-review checklist
230-
231-Before you finish, check:
232-
233-- [ ] Did I read the relevant code and follow local patterns?
234-- [ ] Did I change only what the request required?
235-- [ ] Did I reuse existing logic where appropriate?
236-- [ ] Did I verify every unfamiliar dependency, API, and config
237- field?
238-- [ ] Did I preserve important contracts and caller expectations?
239-- [ ] Did I think through edge cases and failure paths?
240-- [ ] Did I avoid speculative abstractions and unrelated cleanup?
241-- [ ] Did I run the relevant checks, or clearly say what I could
242- not verify?
243-- [ ] Does my summary match the actual diff exactly?
244-
245-## Anti-patterns to avoid
246-
247-- **The Hallucinated Dependency.** Adding a package, API, or tool
248- without verifying that it exists and is appropriate.
249-- **The Shotgun Edit.** Touching many files or concerns for a
250- small request.
251-- **The Duplicate.** Reimplementing logic that already exists in
252- the repo.
253-- **The Spec Drift.** Solving a nearby problem instead of the one
254- the user asked for.
255-- **The Context Drop.** Ignoring repo-local conventions, helpers,
256- architecture, or deployment constraints.
257-- **The Ghost Contract.** Silently changing behavior that callers,
258- data, or integrations depend on.
259-- **The Test Dodger.** Deleting, weakening, or skipping tests to
260- make the change appear correct.
261-- **The Hidden Dependency.** Writing code that only works because
262- of undeclared setup, implicit state, or missing runtime pieces.
263-- **The PR Fiction.** Claiming a change was implemented or
264- verified when the diff and checks do not prove that.
265-- **The TODO Patch.** Leaving behind code you cannot explain,
266- incomplete adaptation, or uncertainty disguised as a finished
267- implementation.
268-
269-## Boundaries
270-
271-This skill is for implementing and refactoring production code.
272-When the task becomes primarily one of these, use the specialized
273-skill too:
274-
275-- **Debugging a failure** → `systematic-debugging`
276-- **Writing or reviewing tests** → `testing-practices`
277-- **Designing or refining a user interface** → `ui-design`
.agents/skills/programming-practices/references/research-notes.md+0−220
@@ -1,220 +0,0 @@
1-# Research Notes for `programming-practices`
2-
3-This file captures the research basis behind the skill. Keep the
4-main `SKILL.md` practical; keep detailed evidence here.
5-
6-## Official guidance
7-
8-### OpenAI Codex — Best practices
9-
10-Source: https://developers.openai.com/codex/learn/best-practices
11-
12-Key takeaways used in the skill:
13-
14-- Provide **goal, context, constraints, and done-when**.
15-- **Plan first** for complex work.
16-- Use `AGENTS.md` for durable project guidance.
17-- Improve reliability with **testing and review**.
18-- Start with the right task context and only add tools that
19- unlock real workflows.
20-
21-### GitHub Docs — Review AI-generated code
22-
23-Source: https://docs.github.com/en/copilot/tutorials/review-ai-generated-code
24-
25-Key takeaways used in the skill:
26-
27-- Start with **functional checks**.
28-- Verify **context and intent**, not just syntax.
29-- Scrutinize **dependencies**, including hallucinated packages
30- and licensing.
31-- Watch for AI-specific pitfalls like ignored constraints,
32- hallucinated APIs, and deleted tests.
33-- Use CI, static analysis, and collaborative review.
34-
35-### Google Cloud Blog — Five Best Practices for Using AI Coding Assistants
36-
37-Source: https://cloud.google.com/blog/topics/developers-practitioners/five-best-practices-for-using-ai-coding-assistants
38-
39-Key takeaways used in the skill:
40-
41-- Choose the right AI tool for the task.
42-- Document the repo early so later generation is grounded.
43-- **Make a plan** before executing complex work.
44-- Prompt with relevant detail.
45-- Preserve cross-session context in durable files.
46-
47-## Research on recurring failure modes
48-
49-### LLM Hallucinations in Practical Code Generation (PACMSE / 2025)
50-
51-Source: https://dl.acm.org/doi/10.1145/3728894
52-Also available as preprint: https://arxiv.org/pdf/2409.20550
53-
54-Why it matters:
55-
56-- Focuses on **repository-level** generation rather than isolated
57- toy functions.
58-- Identifies three major hallucination categories:
59- - Task Requirement Conflicts
60- - Factual Knowledge Conflicts
61- - Project Context Conflicts
62-- Highlights four contributing factors:
63- - training data quality
64- - intention understanding capacity
65- - knowledge acquisition capacity
66- - repository-level context awareness
67-
68-How it shaped the skill:
69-
70-- Read the surrounding code first.
71-- Match repo-local conventions.
72-- Verify APIs and project assumptions.
73-- Treat repo context as part of correctness.
74-
75-### Beyond Functional Correctness: Exploring Hallucinations in LLM-Generated Code (2024)
76-
77-Source: https://arxiv.org/html/2404.00971v3
78-
79-Why it matters:
80-
81-- Builds a broader taxonomy of code hallucinations.
82-- Shows that failures are not just about failing tests; they also
83- affect maintainability, readability, efficiency, and alignment
84- with user intent.
85-
86-How it shaped the skill:
87-
88-- Do not equate plausible output with correct output.
89-- Check intent alignment, not just compilability.
90-
91-### We Have a Package for You! / Package Hallucinations (USENIX Security 2025)
92-
93-USENIX summary: https://www.usenix.org/publications/loginonline/we-have-package-you-comprehensive-analysis-package-hallucinations-code
94-Paper repo summary: https://github.com/Spracks/PackageHallucination
95-ArXiv preprint: https://arxiv.org/pdf/2406.10279
96-
97-Key findings referenced in the skill:
98-
99-- 576,000 code samples analyzed across 16 LLMs.
100-- Average hallucinated package rate was at least:
101- - **5.2%** for commercial models
102- - **21.7%** for open-source models
103-- **205,474** unique hallucinated package names were found.
104-
105-How it shaped the skill:
106-
107-- Never introduce a dependency without verification.
108-- Treat unfamiliar package suggestions as a supply-chain risk.
109-
110-### More Code, Less Reuse: Investigating Code Quality and Reviewer Sentiment towards AI-generated Pull Requests (2026 preprint)
111-
112-Source: https://arxiv.org/abs/2601.21276
113-
114-Why it matters:
115-
116-- Reports that agent-authored PRs frequently miss reuse
117- opportunities and contain more redundancy than human PRs.
118-- Notes a disconnect between objective quality issues and often
119- neutral or positive reviewer sentiment.
120-
121-How it shaped the skill:
122-
123-- Search for existing helpers before adding new logic.
124-- Do not trust surface plausibility alone.
125-- Favor reuse over near-duplicate implementations.
126-
127-### Where Do AI Coding Agents Fail? An Empirical Study of Failed Agentic Pull Requests in GitHub (2026 preprint)
128-
129-Source: https://arxiv.org/abs/2601.15195v1
130-
131-Key findings:
132-
133-- Large-scale study of **33k** agent-authored PRs.
134-- Not-merged PRs tended to be larger, touch more files, and fail
135- CI/CD more often.
136-- Rejection reasons included duplicate PRs, unwanted feature
137- implementations, and agent misalignment.
138-
139-How it shaped the skill:
140-
141-- Keep changes small and scoped.
142-- Avoid broad edits for narrow requests.
143-- Stay aligned with the user's stated task.
144-
145-### Analyzing Message-Code Inconsistency in AI Coding Agent-Authored Pull Requests (2026 preprint)
146-
147-Source: https://arxiv.org/abs/2601.04886
148-
149-Key findings:
150-
151-- Analyzed **23,247** agentic PRs.
152-- **1.7%** showed high message-code inconsistency.
153-- The most common inconsistency type was descriptions claiming
154- unimplemented changes (**45.4%**).
155-- High-inconsistency PRs had lower acceptance rates and took
156- longer to merge.
157-
158-How it shaped the skill:
159-
160-- Summaries must match the diff.
161-- Do not overstate what changed or what was verified.
162-
163-### AI-Generated Code Is Not Reproducible (Yet): An Empirical Study of Dependency Gaps in LLM-Based Coding Agents (2026 preprint)
164-
165-Source: https://arxiv.org/abs/2512.22387
166-
167-Key findings:
168-
169-- Evaluated 300 generated projects across Python, JavaScript,
170- and Java.
171-- Only **68.3%** executed successfully out of the box in a clean
172- environment.
173-- Observed a **13.5x** average expansion from declared to actual
174- runtime dependencies.
175-
176-How it shaped the skill:
177-
178-- Hidden dependencies are common.
179-- Working in one environment is not proof that setup is correct.
180-- Make runtime assumptions explicit.
181-
182-### "TODO: Fix the Mess Gemini Created": Towards Understanding GenAI-Induced Self-Admitted Technical Debt (2026 preprint)
183-
184-Source: https://arxiv.org/abs/2601.07786
185-
186-Why it matters:
187-
188-- Found recurring self-admitted debt patterns in AI-generated
189- code: postponed testing, incomplete adaptation, and limited
190- understanding of what the code actually does.
191-
192-How it shaped the skill:
193-
194-- Do not ship code you cannot explain.
195-- Do not leave uncertainty disguised as completion.
196-
197-## Notes on evidence quality
198-
199-- The official docs above are vendor guidance and reflect current
200- operational best practices.
201-- The package hallucination work and the PACMSE repository-level
202- hallucination paper are strong anchors because they study
203- code-generation failure modes directly.
204-- Several 2026 papers cited here are preprints. They are still
205- useful because they converge on the same practical patterns:
206- larger diffs, poorer reuse, hidden dependencies, overclaiming,
207- and context misalignment.
208-
209-## Practical synthesis
210-
211-Across the sources, the same engineering advice keeps showing up:
212-
213-1. Give the agent the right context.
214-2. Plan before coding on complex tasks.
215-3. Follow repo-local patterns.
216-4. Reuse existing code before inventing new abstractions.
217-5. Verify dependencies, APIs, and environment assumptions.
218-6. Keep diffs small and scoped.
219-7. Run checks.
220-8. Report exactly what changed and what was verified.
.agents/skills/systematic-debugging/CREATION-LOG.md+119−0
@@ -0,0 +1,119 @@
1+# Creation Log: Systematic Debugging Skill
2+
3+Reference example of extracting, structuring, and bulletproofing a critical skill.
4+
5+## Source Material
6+
7+Extracted debugging framework from `/Users/jesse/.claude/CLAUDE.md`:
8+- 4-phase systematic process (Investigation → Pattern Analysis → Hypothesis → Implementation)
9+- Core mandate: ALWAYS find root cause, NEVER fix symptoms
10+- Rules designed to resist time pressure and rationalization
11+
12+## Extraction Decisions
13+
14+**What to include:**
15+- Complete 4-phase framework with all rules
16+- Anti-shortcuts ("NEVER fix symptom", "STOP and re-analyze")
17+- Pressure-resistant language ("even if faster", "even if I seem in a hurry")
18+- Concrete steps for each phase
19+
20+**What to leave out:**
21+- Project-specific context
22+- Repetitive variations of same rule
23+- Narrative explanations (condensed to principles)
24+
25+## Structure Following skill-creation/SKILL.md
26+
27+1. **Rich when_to_use** - Included symptoms and anti-patterns
28+2. **Type: technique** - Concrete process with steps
29+3. **Keywords** - "root cause", "symptom", "workaround", "debugging", "investigation"
30+4. **Flowchart** - Decision point for "fix failed" → re-analyze vs add more fixes
31+5. **Phase-by-phase breakdown** - Scannable checklist format
32+6. **Anti-patterns section** - What NOT to do (critical for this skill)
33+
34+## Bulletproofing Elements
35+
36+Framework designed to resist rationalization under pressure:
37+
38+### Language Choices
39+- "ALWAYS" / "NEVER" (not "should" / "try to")
40+- "even if faster" / "even if I seem in a hurry"
41+- "STOP and re-analyze" (explicit pause)
42+- "Don't skip past" (catches the actual behavior)
43+
44+### Structural Defenses
45+- **Phase 1 required** - Can't skip to implementation
46+- **Single hypothesis rule** - Forces thinking, prevents shotgun fixes
47+- **Explicit failure mode** - "IF your first fix doesn't work" with mandatory action
48+- **Anti-patterns section** - Shows exactly what shortcuts look like
49+
50+### Redundancy
51+- Root cause mandate in overview + when_to_use + Phase 1 + implementation rules
52+- "NEVER fix symptom" appears 4 times in different contexts
53+- Each phase has explicit "don't skip" guidance
54+
55+## Testing Approach
56+
57+Created 4 validation tests following skills/meta/testing-skills-with-subagents:
58+
59+### Test 1: Academic Context (No Pressure)
60+- Simple bug, no time pressure
61+- **Result:** Perfect compliance, complete investigation
62+
63+### Test 2: Time Pressure + Obvious Quick Fix
64+- User "in a hurry", symptom fix looks easy
65+- **Result:** Resisted shortcut, followed full process, found real root cause
66+
67+### Test 3: Complex System + Uncertainty
68+- Multi-layer failure, unclear if can find root cause
69+- **Result:** Systematic investigation, traced through all layers, found source
70+
71+### Test 4: Failed First Fix
72+- Hypothesis doesn't work, temptation to add more fixes
73+- **Result:** Stopped, re-analyzed, formed new hypothesis (no shotgun)
74+
75+**All tests passed.** No rationalizations found.
76+
77+## Iterations
78+
79+### Initial Version
80+- Complete 4-phase framework
81+- Anti-patterns section
82+- Flowchart for "fix failed" decision
83+
84+### Enhancement 1: TDD Reference
85+- Added link to skills/testing/test-driven-development
86+- Note explaining TDD's "simplest code" ≠ debugging's "root cause"
87+- Prevents confusion between methodologies
88+
89+## Final Outcome
90+
91+Bulletproof skill that:
92+- ✅ Clearly mandates root cause investigation
93+- ✅ Resists time pressure rationalization
94+- ✅ Provides concrete steps for each phase
95+- ✅ Shows anti-patterns explicitly
96+- ✅ Tested under multiple pressure scenarios
97+- ✅ Clarifies relationship to TDD
98+- ✅ Ready for use
99+
100+## Key Insight
101+
102+**Most important bulletproofing:** Anti-patterns section showing exact shortcuts that feel justified in the moment. When Claude thinks "I'll just add this one quick fix", seeing that exact pattern listed as wrong creates cognitive friction.
103+
104+## Usage Example
105+
106+When encountering a bug:
107+1. Load skill: skills/debugging/systematic-debugging
108+2. Read overview (10 sec) - reminded of mandate
109+3. Follow Phase 1 checklist - forced investigation
110+4. If tempted to skip - see anti-pattern, stop
111+5. Complete all phases - root cause found
112+
113+**Time investment:** 5-10 minutes
114+**Time saved:** Hours of symptom-whack-a-mole
115+
116+---
117+
118+*Created: 2025-10-03*
119+*Purpose: Reference example for skill extraction and bulletproofing*
.agents/skills/systematic-debugging/SKILL.md+250−147
@@ -1,193 +1,296 @@
11 ---
22 name: systematic-debugging
3-description: >
4- Diagnose and fix bugs using a structured, hypothesis-driven process.
5- Use when the user reports a bug, error, unexpected behavior, test
6- failure, crash, or regression. Also use when the user says "this
7- doesn't work", "help me debug", "find the bug", "why is this
8- failing", "this broke", or "track down this issue". Use proactively
9- when you encounter an error during your own work that requires
10- diagnosis beyond a trivial fix.
11-license: MIT
12-metadata:
13- author: xonecas
14- version: "1.0"
3+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
154 ---
165
176 # Systematic Debugging
187
19-You are a methodical debugger. You never guess randomly or make
20-shotgun changes. Every action you take is driven by a hypothesis,
21-and every hypothesis is tested before you act on it.
8+## Overview
229
23-## Core principle
10+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
2411
25-Debugging is search. A program may execute millions of instructions;
26-your job is to narrow the search space systematically until you find
27-the defect. Each step should roughly halve the remaining possibilities.
12+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
2813
29-## Before you begin
14+**Violating the letter of this process is violating the spirit of debugging.**
3015
31-1. **Read the error.** Read the full error message, stack trace, or
32- symptom description. Do not skim. Extract: what failed, where it
33- failed, and what inputs were involved.
34-2. **Understand the system.** Before touching code, make sure you
35- understand what the code is supposed to do. Read the relevant
36- source, tests, docs, and config. You cannot find what is wrong
37- if you do not know what is right.
16+## The Iron Law
3817
39-## The debugging process
18+```
19+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
20+```
4021
41-Follow these phases in order. Do not skip ahead.
22+If you haven't completed Phase 1, you cannot propose fixes.
4223
43-### Phase 1 — Reproduce
24+## When to Use
4425
45-Establish a reliable way to trigger the failure.
26+Use for ANY technical issue:
27+- Test failures
28+- Bugs in production
29+- Unexpected behavior
30+- Performance problems
31+- Build failures
32+- Integration issues
4633
47-- Identify the exact inputs, environment, and sequence of steps.
48-- Confirm you can make it fail on demand. If the bug is intermittent,
49- find the uncontrolled condition (timing, state, data) that makes it
50- so and note it.
51-- Minimize the reproduction: strip away anything not required to
52- trigger the failure. Smaller reproductions expose the defect faster.
53-- If you cannot reproduce it, say so. Do not proceed to guess at
54- fixes for a bug you cannot observe.
34+**Use this ESPECIALLY when:**
35+- Under time pressure (emergencies make guessing tempting)
36+- "Just one quick fix" seems obvious
37+- You've already tried multiple fixes
38+- Previous fix didn't work
39+- You don't fully understand the issue
5540
56-### Phase 2 — Localize
41+**Don't skip when:**
42+- Issue seems simple (simple bugs have root causes too)
43+- You're in a hurry (rushing guarantees rework)
44+- Manager wants it fixed NOW (systematic is faster than thrashing)
5745
58-Narrow down where the defect lives using one or more of these
59-strategies. Pick the one best suited to the situation.
46+## The Four Phases
6047
61-**Binary search (divide and conquer)**
62-Split the code path or input in half. Test each half. Recurse into the
63-half that fails. This is the fastest general-purpose strategy.
48+You MUST complete each phase before proceeding to the next.
6449
65-- For regressions: use `git bisect` to find the breaking commit.
66-- For data pipelines: check the midpoint of the pipeline to see if
67- data is already wrong there.
68-- For long functions: add an assertion or log at the midpoint.
50+### Phase 1: Root Cause Investigation
6951
70-**Backward reasoning**
71-Start at the point of failure (the crash, wrong output, bad state).
72-Ask: what produced this value? Trace upstream through the data flow
73-and control flow until you find where correct state became incorrect.
52+**BEFORE attempting ANY fix:**
7453
75-**Differential analysis**
76-Compare a working case to a failing case. What differs between them?
77-Minimize both cases until the difference is as small as possible. The
78-remaining difference contains or points to the defect.
54+1. **Read Error Messages Carefully**
55+ - Don't skip past errors or warnings
56+ - They often contain the exact solution
57+ - Read stack traces completely
58+ - Note line numbers, file paths, error codes
7959
80-**Forward tracing**
81-When you have a suspect area, step through it mentally or with a
82-debugger. Track the actual values at each step against what you
83-expect. The first divergence is your lead.
60+2. **Reproduce Consistently**
61+ - Can you trigger it reliably?
62+ - What are the exact steps?
63+ - Does it happen every time?
64+ - If not reproducible → gather more data, don't guess
8465
85-### Phase 3 — Hypothesize and test
66+3. **Check Recent Changes**
67+ - What changed that could cause this?
68+ - Git diff, recent commits
69+ - New dependencies, config changes
70+ - Environmental differences
8671
87-Once you have a suspect location:
72+4. **Gather Evidence in Multi-Component Systems**
8873
89-1. **State your hypothesis explicitly.** "I believe the bug is in
90- function X because Y, and the root cause is Z."
91-2. **Design a test.** What observation would confirm or refute this
92- hypothesis? Add a log, write an assertion, modify a value, or
93- write a minimal test case.
94-3. **Run the test.** Observe the result.
95-4. **Evaluate.** If confirmed, proceed to Phase 4. If refuted, you
96- gained information — update your mental model and form a new
97- hypothesis. Return to Phase 2 if needed.
74+ **WHEN system has multiple components (CI → build → signing, API → service → database):**
9875
99-Change only one thing at a time. If you change multiple variables
100-simultaneously, you cannot know which change had which effect.
76+ **BEFORE proposing fixes, add diagnostic instrumentation:**
77+ ```
78+ For EACH component boundary:
79+ - Log what data enters component
80+ - Log what data exits component
81+ - Verify environment/config propagation
82+ - Check state at each layer
10183
102-### Phase 4 — Fix
84+ Run once to gather evidence showing WHERE it breaks
85+ THEN analyze evidence to identify failing component
86+ THEN investigate that specific component
87+ ```
10388
104-1. **Fix the root cause**, not the symptom. Ask: why did this defect
105- exist? Is it a logic error, a wrong assumption about an API, a
106- missing edge case, a concurrency issue?
107-2. **Verify the fix.** Run the reproduction from Phase 1. It must
108- now pass. Run the existing test suite. Nothing that previously
109- passed should now fail.
110-3. **Add a regression test** if one does not already exist for this
111- failure mode and the project has a test suite.
89+ **Example (multi-layer system):**
90+ ```bash
91+ # Layer 1: Workflow
92+ echo "=== Secrets available in workflow: ==="
93+ echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
11294
113-### Phase 5 — Validate
95+ # Layer 2: Build script
96+ echo "=== Env vars in build script: ==="
97+ env | grep IDENTITY || echo "IDENTITY not in environment"
11498
115-Before declaring the bug fixed:
99+ # Layer 3: Signing script
100+ echo "=== Keychain state: ==="
101+ security list-keychains
102+ security find-identity -v
116103
117-- Confirm the specific reproduction case passes.
118-- Confirm the broader test suite passes.
119-- Consider related edge cases — could the same class of defect exist
120- nearby? Check, but do not go on a fishing expedition.
104+ # Layer 4: Actual signing
105+ codesign --sign "$IDENTITY" --verbose=4 "$APP"
106+ ```
121107
122-If the fix does not hold under these checks, return to Phase 3.
108+ **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
109+
110+5. **Trace Data Flow**
123111
124-## Audit trail
112+ **WHEN error is deep in call stack:**
125113
126-Keep a running log of your debugging session:
114+ See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
127115
128-- What you observed
129-- What hypothesis you formed
130-- What test you ran
131-- What the result was
116+ **Quick version:**
117+ - Where does bad value originate?
118+ - What called this with bad value?
119+ - Keep tracing up until you find the source
120+ - Fix at source, not at symptom
132121
133-This prevents going in circles and helps if you need to hand off to
134-someone else or revisit the issue later.
122+### Phase 2: Pattern Analysis
123+
124+**Find the pattern before fixing:**
125+
126+1. **Find Working Examples**
127+ - Locate similar working code in same codebase
128+ - What works that's similar to what's broken?
129+
130+2. **Compare Against References**
131+ - If implementing pattern, read reference implementation COMPLETELY
132+ - Don't skim - read every line
133+ - Understand the pattern fully before applying
134+
135+3. **Identify Differences**
136+ - What's different between working and broken?
137+ - List every difference, however small
138+ - Don't assume "that can't matter"
135139
136-## Anti-patterns to avoid
140+4. **Understand Dependencies**
141+ - What other components does this need?
142+ - What settings, config, environment?
143+ - What assumptions does it make?
137144
138-- **Shotgun debugging.** Making random changes hoping something sticks.
139- Every change should be driven by a hypothesis.
140-- **Not reading the error.** The error message is data. It is often
141- the single most informative piece of evidence you have.
142-- **Fixing symptoms.** Wrapping a crash in a try/catch is not a fix.
143- Suppressing a warning is not a fix. Find the root cause.
144-- **Changing multiple things at once.** You lose the ability to reason
145- about cause and effect.
146-- **Trusting assumptions.** Check the plug. Is the right version
147- running? Is the config correct? Is the file actually being loaded?
148- Verify the basics before diving deep.
149-- **Theorizing without looking.** When in doubt, add instrumentation
150- and observe. Data beats speculation.
151-
152-## When you are stuck
145+### Phase 3: Hypothesis and Testing
153146
154-- **Get a fresh perspective.** Describe the problem to the user from
155- scratch — what you know, what you have tried, what you have ruled
156- out. Ask if they have context you are missing.
157-- **Question your assumptions.** List every assumption you are making.
158- Test the least certain one.
159-- **Widen the search.** If you have been focused on one component,
160- consider whether the defect is in a dependency, configuration,
161- environment, or data.
162-
163-## Output format
147+**Scientific method:**
164148
165-When reporting your debugging findings, use this structure:
149+1. **Form Single Hypothesis**
150+ - State clearly: "I think X is the root cause because Y"
151+ - Write it down
152+ - Be specific, not vague
153+
154+2. **Test Minimally**
155+ - Make the SMALLEST possible change to test hypothesis
156+ - One variable at a time
157+ - Don't fix multiple things at once
158+
159+3. **Verify Before Continuing**
160+ - Did it work? Yes → Phase 4
161+ - Didn't work? Form NEW hypothesis
162+ - DON'T add more fixes on top
163+
164+4. **When You Don't Know**
165+ - Say "I don't understand X"
166+ - Don't pretend to know
167+ - Ask for help
168+ - Research more
169+
170+### Phase 4: Implementation
166171
167-```
168-**Symptom**: [what the user reported or what you observed]
172+**Fix the root cause, not the symptom:**
173+
174+1. **Create Failing Test Case**
175+ - Simplest possible reproduction
176+ - Automated test if possible
177+ - One-off test script if no framework
178+ - MUST have before fixing
179+ - Use the `superpowers:test-driven-development` skill for writing proper failing tests
169180
170-**Reproduction**: [minimal steps to trigger the failure]
181+2. **Implement Single Fix**
182+ - Address the root cause identified
183+ - ONE change at a time
184+ - No "while I'm here" improvements
185+ - No bundled refactoring
171186
172-**Root cause**: [the defect — what, where, and why]
187+3. **Verify Fix**
188+ - Test passes now?
189+ - No other tests broken?
190+ - Issue actually resolved?
173191
174-**Fix**: [what you changed and why it addresses the root cause]
192+4. **If Fix Doesn't Work**
193+ - STOP
194+ - Count: How many fixes have you tried?
195+ - If < 3: Return to Phase 1, re-analyze with new information
196+ - **If ≥ 3: STOP and question the architecture (step 5 below)**
197+ - DON'T attempt Fix #4 without architectural discussion
175198
176-**Verification**: [what tests confirm the fix]
177-```
199+5. **If 3+ Fixes Failed: Question Architecture**
200+
201+ **Pattern indicating architectural problem:**
202+ - Each fix reveals new shared state/coupling/problem in different place
203+ - Fixes require "massive refactoring" to implement
204+ - Each fix creates new symptoms elsewhere
205+
206+ **STOP and question fundamentals:**
207+ - Is this pattern fundamentally sound?
208+ - Are we "sticking with it through sheer inertia"?
209+ - Should we refactor architecture vs. continue fixing symptoms?
210+
211+ **Discuss with your human partner before attempting more fixes**
212+
213+ This is NOT a failed hypothesis - this is a wrong architecture.
214+
215+## Red Flags - STOP and Follow Process
216+
217+If you catch yourself thinking:
218+- "Quick fix for now, investigate later"
219+- "Just try changing X and see if it works"
220+- "Add multiple changes, run tests"
221+- "Skip the test, I'll manually verify"
222+- "It's probably X, let me fix that"
223+- "I don't fully understand but this might work"
224+- "Pattern says X but I'll adapt it differently"
225+- "Here are the main problems: [lists fixes without investigation]"
226+- Proposing solutions before tracing data flow
227+- **"One more fix attempt" (when already tried 2+)**
228+- **Each fix reveals new problem in different place**
229+
230+**ALL of these mean: STOP. Return to Phase 1.**
231+
232+**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
233+
234+## your human partner's Signals You're Doing It Wrong
235+
236+**Watch for these redirections:**
237+- "Is that not happening?" - You assumed without verifying
238+- "Will it show us...?" - You should have added evidence gathering
239+- "Stop guessing" - You're proposing fixes without understanding
240+- "Ultrathink this" - Question fundamentals, not just symptoms
241+- "We're stuck?" (frustrated) - Your approach isn't working
242+
243+**When you see these:** STOP. Return to Phase 1.
244+
245+## Common Rationalizations
246+
247+| Excuse | Reality |
248+|--------|---------|
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/condition-based-waiting-example.ts+164−0
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/condition-based-waiting.md+115−0
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/defense-in-depth.md+122−0
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/find-polluter.sh+63−0
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/root-cause-tracing.md+169−0
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/test-academic.md+14−0
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/test-pressure-1.md+58−0
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/test-pressure-2.md+68−0
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/test-pressure-3.md+69−0
Cut short: this commit's diff is over 1000 lines.
.agents/skills/testing-practices/SKILL.md+0−328
Cut short: this commit's diff is over 1000 lines.