Discover skills in this marketplace that match your workflow. Accepts a workload or task description, scans all released skills, and recommends the best matches with install commands. Use when users ask 'what skills are available', 'find a skill for X', 'which skill helps me with Y', 'what can I install', or 'recommend skills for my workflow'.

2026-05-232

arch-gather-nfr

amdmax/claude_marketplace

Collect non-functional requirements through interactive Q&A. Asks targeted questions about performance, scalability, security, reliability, and cost constraints. Invokable with /gather-nfr.

2026-05-222

review-compliance

amdmax/claude_marketplace

Validates business requirements compliance - generates OpenAPI specs, creates contract tests, and ensures acceptance criteria alignment

2026-05-222

git-commit

amdmax/claude_marketplace

Create git commits with configurable numbering (issue-based or sequential). Analyzes staged changes and generates commit messages following project conventions. Optionally creates GitHub issues if no active story exists.

2026-05-222

agent-architect

amdmax/claude_marketplace

Spawn the Architect agent to map business requirements to implementation details, produce implementation briefs, assess risks, and create ADRs. Use for standalone architecture tasks without the full agile team.

2026-05-172

name	debug
description	Hypothesis-driven bug investigation with mandatory regression tests
version	1.0.0
invocations	["/debug","/debug <issue-number>"]
category	development-tools

Debug Skill - Hypothesis-Driven Bug Investigation

Systematic bug investigation using the scientific method: generate hypotheses, test them through research, implement fixes with user approval, and create mandatory regression tests to prevent recurrence.

Quick Start

# Start debugging (prompts for issue selection or creation)
/debug

# Debug specific issue
/debug 123

Core Workflow

1. Issue Selection/Creation
   ↓
2. Hypothesis Generation (3-5 hypotheses)
   ↓
3. Research Loop (autonomous)
   ↓
4. Fix Implementation (requires user approval)
   ↓
5. Test Generation (mandatory, validated)
   ↓
6. Commit & Pull Request

Configuration

User-configurable options in @config.yaml:

Hypothesis count and types
Research depth (quick/thorough/exhaustive)
Test validation requirements
Commit/PR behavior

Reference Documentation

Hypotheses: @references/hypotheses.md
Research Loop: @references/research-loop.md
Fix Implementation: @references/fix-implementation.md
Testing: @references/testing.md
Commit & PR: @references/commit-and-pr.md
State Management: @references/hypothesis-tracking.md
Research Strategies: @references/research-strategies.md
Test Patterns: @references/test-generation-guide.md
Examples: @references/examples.md

Phase 1: Issue Creation & Selection

Invocation Patterns

Without Issue Number

/debug

Process:

Check for existing session (.claude/active-debug.json)
If session exists → Offer to resume or archive
List open bugs: gh issue list --label "bug" --state open
User selects from list OR creates new issue

With Issue Number

/debug 123

Process:

Check for existing session
Fetch issue: gh issue view 123 --json number,title,body,url
Verify issue has "bug" label
Initialize debug session

Issue Creation

If user doesn't provide an issue number and wants to create one:

/create-story

Required Information:

Title (brief description of bug)
Label "bug" (automatically added)
Optional: reproduction steps, error messages

Example:

Title: Authentication fails with expired tokens
Label: bug
Body: Users with expired tokens can still authenticate.
      Expected: Reject expired tokens
      Actual: Accepts tokens at exact expiration time

Session Initialization

After issue selected/created:

.claude/skills/debug/scripts/hypothesis-tracker.py init \
  <issue-number> \
  "<title>" \
  "<url>"

Creates: .claude/active-debug.json

{
  "issueNumber": 123,
  "title": "Authentication fails with expired tokens",
  "url": "https://github.com/owner/repo/issues/123",
  "sessionId": "debug-123-20260202-143022",
  "status": "investigating",
  "currentPhase": "hypothesis_generation",
  "hypotheses": [],
  "fix": null,
  "tests": null
}

Also Creates: $AGENT_DOCS_DIR/active-story.yaml (for /gh:commit integration)

Phase 2: Hypothesis Generation

Generate 3-5 hypotheses ranked by confidence. See @references/hypotheses.md for types, commands, and confidence criteria.

Phase 3: Research Loop (Autonomous)

Investigate hypotheses from highest confidence first; collect evidence; mark CONFIRMED/REJECTED/NEEDS_INFO. See @references/research-loop.md for process, commands, and depth settings.

Phase 4: Fix Implementation

IMPORTANT: User must approve fix before implementation. See @references/fix-implementation.md for proposal format, user responses, and recording the fix.

Phase 5: Test Generation (Mandatory)

CANNOT SKIP — regression tests required for all bug fixes (tests.required: true).

Generate minimum 3 tests: reproduction (must fail before fix), edge cases, regression protection. See @references/testing.md for structure, location, validation steps, and blocking criteria.

Phase 6: Commit & Pull Request

Two separate commits (fix + tests), then /mr. See @references/commit-and-pr.md for commit format, PR description, and session archive.

Error Handling

No Active Session

Error: No active debug session

Solution: Run /debug to start new session.

Session Already Exists

Solution:

hypothesis-tracker.py status   # check current session
hypothesis-tracker.py archive  # archive if done
/debug                         # or resume

Invalid Hypothesis Type

Use valid type: logic_error, missing_validation, race_condition, configuration, dependency

Tests Not Validated

Run fail-before/pass-after validation. See @references/testing.md.

Test Validation Failed

🛑 BLOCKED: Cannot proceed without validated regression tests

Review reproduction test: exact bug conditions, correct behavior assertion, proper mocks.

Resuming Interrupted Sessions

hypothesis-tracker.py status
/debug

State preserved in .claude/active-debug.json — continues from current phase.

Integration Points

With /create-story

Invoked when user wants to create a new bug report without an issue number.

With /gh:commit

Reads $AGENT_DOCS_DIR/active-story.yaml for issue number, grouping (AIGCODE-###a), and "Fixes #123" reference.

With /mr

Creates PR with investigation summary, hypothesis outcomes, test validation results, and issue links.

Tips & Best Practices

Hypothesis Generation: Start with most obvious causes. Use error messages as primary evidence. Consider recent git changes.

Research: Collect evidence systematically (file:line:note). Know when to stop. Use git history for context.

Fix Design: Keep changes minimal. Consider edge cases and backwards compatibility.

Testing: Focus on reproduction first. Ensure tests are deterministic. Use clear test names.

Validation: NEVER skip. Verify fail-before/pass-after. Run full suite to catch regressions.

Configuration Reference

See @config.yaml for all options:

hypothesis_generation:
  initial_count: 5
  types_to_consider: [...]

research:
  max_rounds: 3
  depth: "thorough"
  include_git_history: true

tests:
  required: true              # CANNOT be false
  validate_before_after: true # CANNOT be false
  min_test_count: 3

commit:
  use_skill: true
  separate_fix_and_tests: true

pull_request:
  use_skill: true
  include_investigation_summary: true
  include_hypothesis_outcomes: true
  include_test_validation: true

Troubleshooting

Script not found: chmod +x .claude/skills/debug/scripts/hypothesis-tracker.py

Python not found: python3 --version — update shebang if needed.

State file corrupted: cp .claude/active-debug.json .claude/active-debug.json.bak then edit or delete.

Tests won't fail before fix: Verify test triggers exact bug condition, assertion tests CORRECT behavior, proper mocks/fixtures.

Can't find test location:

find . -name "*.test.*" -o -name "*.spec.*"
grep -r "testMatch" jest.config.js