agentleFS
ekirtonekirton/Poule/.claude/skills/diagnose/SKILL.md

diagnose

Skill0 starsChanged 8 months agoApache-2.0View on GitHub

Investigate a bug report — find root cause, trace it up the SDD authority chain, and auto-fix if the problem is within autonomous layers (specification and below). Use when given a bug description, error report, or failing test.

193 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use zoom-out, to-prd and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • victorgarciaesgiSkill

    zoom-out

    Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.

    Also in 61 projects that use this

  • GoogleSkill

    to-prd

    Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.

    Also in 56 projects that use this

  • GoogleSkill

    to-issues

    Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices.

    Also in 53 projects that use this

  • simo97Skill

    edit-article

    The user will invoke this skill to help them edit an article.

    Also in 17 projects that use this

  • simo97Skill

    write-a-skill

    Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.

    Also in 44 projects that use this

  • AnasX7Skill

    setup-pre-commit

    Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.

    Also in 27 projects that use this

  • +4 more from simo97

The file

Show its rules and text

We split this skill into the rules it gives an agent

20 rules. 0 are common, 9 are distinctive, and 11 are very specific to this project.

  • 0

    Common

    Most of the 175 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 11

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When the agent returns, summarize the root cause in 2-3 sentences with specific file:line references.

    line 18
  2. Distinctive:

    Read each layer's documents to find the highest layer that needs correction.

    line 22
  3. Very specific:

    Read the specification that governs this behavior (in specification/).

    line 24
  4. Very specific:

    If the spec appears wrong or incomplete, read the parent architecture document (in doc/architecture/).

    line 28
  5. Very specific:

    If the architecture appears wrong, read the feature document (in doc/features/).

    line 32
  6. Very specific:

    If the feature doc appears wrong, read the PRD (in doc/requirements/).

    line 35
  7. Distinctive:

    Read the parent architecture document.

    line 53
  8. Very specific:

    If a problem is identified with the architecture while fixing the spec, write a detailed description to doc/architecture/feedback/ and stop.

    line 55
  9. Distinctive:

    Write failing tests first, then implement until tests pass.

    line 61
  10. Very specific:

    Read the blast radius from $CLAUDE_PROJECT_DIR/sdd-blast-radius if it exists.

    line 63
  11. Distinctive:

    Write or update tests that reproduce the bug or cover the spec change within the blast radius.

    line 65
  12. Distinctive:

    Do not change specifications.

    line 66
  13. Very specific:

    Run python -m pytest test/ -x -q.

    line 67
  14. Distinctive:

    Write the implementation to make tests pass.

    line 69
  15. Very specific:

    Run python -m pytest test/ -x -q after each significant change.

    line 70
  16. Very specific:

    Write to doc/architecture/feedback/, notify the user, and stop.

    line 80
  17. Very specific:

    Remove $CLAUDE_PROJECT_DIR/sdd-blast-radius if it exists.

    line 86
  18. Very specific:

    Check off completed tasks in tasks/ (update - [ ] to - [x]).

    line 87
  19. Distinctive:

    If any feedback files still exist, notify the user and stop.

    line 88
  20. Distinctive:

    Do not make a PR — the user decides when the branch is ready.

    line 103

“Common” is measured: kept by at least 6 in 10 of the 175 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Diagnose a bug and triage it to the correct SDD layer: $ARGUMENTS

Phase 1: Find the root cause

Delegate the investigation to an Explore subagent to keep the main context clean.

  1. Launch an Explore agent with this prompt:
    • The bug description from the user
    • "Search the codebase for the relevant code paths. Trace the call chain to find where the behavior diverges. Check handlers, validation, tests. Return: the root cause (file, function, line, why), and which source/test/spec files are involved."
  2. When the agent returns, summarize the root cause in 2-3 sentences with specific file:line references.

Phase 2: Triage up the authority chain

Read each layer's documents to find the highest layer that needs correction. Only read the specific documents relevant to the bug — do not read broadly.

  1. Read the specification that governs this behavior (in specification/). Ask:
    • Does the spec correctly describe the expected behavior?
    • Is the bug a deviation from the spec, or does the spec itself have a gap?
  2. If the spec appears wrong or incomplete, read the parent architecture document (in doc/architecture/). Ask:
    • Does the architecture correctly describe the design?
    • Did the spec misinterpret the architecture, or is the architecture flawed?
  3. If the architecture appears wrong, read the feature document (in doc/features/). Ask:
    • Does the feature doc correctly capture what the system should do?
  4. If the feature doc appears wrong, read the PRD (in doc/requirements/). Ask:
    • Is the requirement clearly stated?

Phase 3: Decide and act

  1. Determine the highest affected layer from the triage. Do NOT present a report table yet — act first, report at the end.

    If the fix requires changes to doc/ layers (requirements, features, or architecture):

    • These require human approval. Present the triage table (same format as step 29), then present 2-3 options with critical analysis and a recommendation. Wait for the user to decide before proceeding. Stop here.

    If the fix starts at specification/ or below (all doc/ layers are OK):

    • This is within autonomous scope. Do not wait for user approval. Proceed directly to Phase 4.

Phase 4: Fix the specification (if needed)

Skip this phase if the specification is correct (the bug is purely an implementation deviation). Go directly to Phase 5.

  1. Run: echo "specification" > $CLAUDE_PROJECT_DIR/sdd-layer
  2. Read the parent architecture document.
  3. Fix the specification gap or error in specification/.
  4. If a problem is identified with the architecture while fixing the spec, write a detailed description to doc/architecture/feedback/ and stop. Notify the user — architecture changes require human approval.
  5. Record the blast radius — write changed spec filenames to $CLAUDE_PROJECT_DIR/sdd-blast-radius: echo "specification/channels.md specification/storage.md" > $CLAUDE_PROJECT_DIR/sdd-blast-radius

Phase 5: Tests and implementation (TDD)

Write failing tests first, then implement until tests pass. Track feedback cycles (any return to an earlier step from a feedback resolution counts as one cycle).

  1. Read the blast radius from $CLAUDE_PROJECT_DIR/sdd-blast-radius if it exists.
  2. Run: echo "tests" > $CLAUDE_PROJECT_DIR/sdd-layer
  3. Write or update tests that reproduce the bug or cover the spec change within the blast radius.
  4. Do not change specifications. If a spec problem is found, go to step 21.
  5. Run python -m pytest test/ -x -q. New tests covering the change should fail. Existing tests may pass or fail.
  6. Run: echo "implementation" > $CLAUDE_PROJECT_DIR/sdd-layer
  7. Write the implementation to make tests pass. Do not change tests or specifications.
  8. Run python -m pytest test/ -x -q after each significant change. When all tests pass, proceed to Phase 6.
  9. If a spec problem is found (during tests or implementation):
    • Run: echo "specification" > $CLAUDE_PROJECT_DIR/sdd-layer
    • Fix the specification. Delete the feedback file.
    • Increment feedback cycle count. Return to step 14.
  10. If a test problem is found (during implementation):
    • Run: echo "tests" > $CLAUDE_PROJECT_DIR/sdd-layer
    • Fix the test. Delete the feedback file.
    • Increment feedback cycle count. Return to step 18.
  11. If an architecture problem is found:
    • Write to doc/architecture/feedback/, notify the user, and stop.
  12. After 3 feedback cycles, stop and present the situation to the user: summarize what was attempted, what keeps failing, and ask for direction.

Phase 6: Completion

  1. Run: echo "free" > $CLAUDE_PROJECT_DIR/sdd-layer
  2. Remove $CLAUDE_PROJECT_DIR/sdd-blast-radius if it exists.
  3. Check off completed tasks in tasks/ (update - [ ] to - [x]).
  4. If any feedback files still exist, notify the user and stop.
  5. Present the triage table:

Root cause: <2-3 sentence summary with specific file:line references>

LayerDocumentStatusFinding
Requirementsdoc/requirements/X.mdOK / GAP / ERRORbrief note
Featuresdoc/features/X.mdOK / GAP / ERRORbrief note
Architecturedoc/architecture/X.mdOK / GAP / ERRORbrief note
Specificationspecification/X.mdOK / GAP / ERRORbrief note
Teststest/X.pyOK / GAP / ERRORbrief note
Implementationsrc/poule/X.pyOK / GAP / ERRORbrief note
  1. Report what was done and which files were changed.
  2. Do not make a PR — the user decides when the branch is ready.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.