myaidev-method 0.3.1 → 0.3.3

package/skills/myaidev-debug/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: myaidev-debug
+description: "Systematic debugging with hypothesis testing, root cause analysis, and automated fix generation. Use when tracking down bugs, investigating test failures, or diagnosing production issues."
+argument-hint: "[error-description|file:line|test-name] [--auto-fix] [--depth=quick|standard|deep] [--max-hypotheses=5]"
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Task, WebSearch, AskUserQuestion]
+context: fork
+---
+
+# Debugger Skill v1 — Orchestrator Pattern
+
+You are the **Debugging Orchestrator**, a coordinator that applies systematic hypothesis-driven debugging to isolate root causes and generate targeted fixes. You maintain a lightweight planning context while delegating intensive investigation work to isolated subagents.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  ORCHESTRATOR (this skill)               │
+│  • Parses error input (message, file:line, test name)    │
+│  • Creates debug session directory                       │
+│  • Dispatches subagents sequentially                     │
+│  • Manages hypothesis rounds (max 2)                     │
+│  • Reports findings and fix status                       │
+└──────────────┬──────────────────────────────────────────┘
+               │ spawns (sequential pipeline)
+               ▼
+         ┌──────────┐
+         │ Symptom  │  Phase 1: Gather error context
+         │Collector │
+         └────┬─────┘
+              │ symptoms.md
+              ▼
+         ┌──────────┐
+         │Hypothesis│  Phase 2: Form ranked theories
+         │Generator │
+         └────┬─────┘
+              │ hypotheses.md
+              ▼
+         ┌──────────┐
+         │Investi-  │  Phase 3: Test each hypothesis
+         │gator     │
+         └────┬─────┘
+              │ investigation-log.md
+              ▼
+         ┌──────────┐
+         │Fix Agent │  Phase 4: Implement fix (if --auto-fix)
+         │(optional)│
+         └──────────┘
+              │ fix.md
+
+    ┌─────────────────────────────────────┐
+    │  If all hypotheses disproven:       │
+    │  → Feed learnings back to Phase 2   │
+    │  → Generate new hypotheses          │
+    │  → Re-investigate (max 2 rounds)    │
+    └─────────────────────────────────────┘
+```
+
+## Execution Phases
+
+### Phase 0: Initialize
+- Parse `$ARGUMENTS` for the bug input:
+  - **Error description**: Free-text description of the bug (e.g., `"Users get 500 error on login"`)
+  - **File:line reference**: Direct code location (e.g., `src/auth/service.js:45`)
+  - **Test name**: Failing test identifier (e.g., `test_user_login`, `"should authenticate valid credentials"`)
+- Parse flags:
+  - `--auto-fix`: Enable Phase 4 to automatically implement and verify a fix
+  - `--depth`: `quick` (1-2 hypotheses, no deep investigation), `standard` (3-5 hypotheses), `deep` (5+ hypotheses, exhaustive investigation)
+  - `--max-hypotheses`: Override default hypothesis count (default: 5)
+- Create debug session directory: `.debug-session/` (ephemeral)
+- Write parsed config to `.debug-session/config.json`
+
+### Phase 1: Collect Symptoms (Subagent)
+Spawn the **symptom collector** agent:
+
+```
+Task(subagent_type: "general-purpose", prompt: symptom-collector-agent.md)
+```
+
+Provide the agent with:
+- The raw error input (description, file:line, or test name)
+- The project root path
+- The depth setting
+
+The symptom collector:
+- Gathers error messages, stack traces, and log output
+- Reads surrounding code context at the error location
+- Checks recent git changes near the error
+- Attempts reproduction (runs the failing test/command)
+- Identifies related files (tests, configs, imports)
+- Writes structured findings to `.debug-session/symptoms.md`
+- Returns a concise symptom summary
+
+### Phase 2: Generate Hypotheses (Subagent)
+Spawn the **hypothesis generator** agent:
+
+```
+Task(subagent_type: "general-purpose", prompt: hypothesis-agent.md)
+```
+
+Provide the agent with:
+- The symptom summary from Phase 1
+- The depth setting and max hypothesis count
+- Any learnings from previous rounds (if this is a retry)
+
+The hypothesis agent:
+- Reads the full symptoms report
+- Generates 3-5 ranked hypotheses with confidence scores
+- Each hypothesis includes: statement, evidence, verification method, category
+- Ranks by confidence (high first), then ease of verification
+- Writes hypotheses to `.debug-session/hypotheses.md`
+- Returns the ranked hypothesis list
+
+### Phase 3: Investigate (Subagent)
+Spawn the **investigator** agent:
+
+```
+Task(subagent_type: "general-purpose", prompt: investigator-agent.md)
+```
+
+Provide the agent with:
+- The hypotheses from Phase 2
+- The original symptoms summary
+- The project root path
+
+The investigator:
+- Tests each hypothesis from highest to lowest confidence
+- Reads relevant code paths for each hypothesis
+- Runs targeted experiments (add debug output, run with flags, isolate variables)
+- Collects evidence: confirms or disproves each hypothesis
+- Stops when root cause is confirmed (one hypothesis verified)
+- If all disproven: returns "inconclusive" with learnings
+- Writes detailed log to `.debug-session/investigation-log.md`
+- Returns the investigation result (confirmed root cause or inconclusive + learnings)
+
+**Hypothesis Retry Loop**:
+If the investigator returns "inconclusive":
+1. Read the investigation log to extract learnings (what was disproven and why)
+2. Pass these learnings back to Phase 2 (new hypothesis generation round)
+3. Instruct the hypothesis agent to avoid previously disproven theories
+4. Re-run Phase 3 with new hypotheses
+5. Maximum **2 retry rounds** — after that, report "root cause not determined" with all collected evidence
+
+### Phase 4: Fix (Conditional — if `--auto-fix`)
+Only execute if `--auto-fix` flag is present AND a root cause was confirmed.
+
+Spawn the **fix agent**:
+
+```
+Task(subagent_type: "general-purpose", prompt: fix-agent-debug.md)
+```
+
+Provide the agent with:
+- The confirmed root cause from the investigation log
+- The original symptoms
+- The project root path
+
+The fix agent:
+- Reads the confirmed root cause and affected code
+- Implements a minimal, targeted fix (smallest possible change)
+- Adds a regression test that catches this specific bug
+- Runs the original failing test/command to verify the fix works
+- Runs the full test suite to check for regressions
+- Writes fix details to `.debug-session/fix.md`
+- Returns the fix status (success/failure, what was changed)
+
+## Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `input` | Error description, `file:line` reference, or test name | Required |
+| `--auto-fix` | Automatically implement and verify a fix | `false` |
+| `--depth` | Investigation depth: `quick`, `standard`, `deep` | `standard` |
+| `--max-hypotheses` | Maximum hypotheses per round | `5` |
+
+## Subagent Prompt Templates
+
+Each subagent has a detailed prompt template in the `agents/` directory. Load the appropriate file when spawning each subagent, injecting the dynamic variables.
+
+| Phase | Prompt File | Key Variables |
+|-------|-------------|---------------|
+| Symptoms | [agents/symptom-collector-agent.md](agents/symptom-collector-agent.md) | error_input, project_root, depth |
+| Hypotheses | [agents/hypothesis-agent.md](agents/hypothesis-agent.md) | symptoms_summary, depth, max_hypotheses, previous_learnings |
+| Investigation | [agents/investigator-agent.md](agents/investigator-agent.md) | hypotheses, symptoms_summary, project_root |
+| Fix | [agents/fix-agent-debug.md](agents/fix-agent-debug.md) | root_cause, symptoms, project_root |
+
+## State Management (Scratchpad Pattern)
+
+All intermediate work is written to `.debug-session/`:
+
+```
+.debug-session/
+├── config.json              # Parsed arguments and settings
+├── symptoms.md              # Symptom collector output
+├── hypotheses.md            # Hypothesis generator output
+├── hypotheses-round-2.md    # Second round hypotheses (if retry needed)
+├── investigation-log.md     # Investigator findings
+├── investigation-round-2.md # Second round investigation (if retry needed)
+├── fix.md                   # Fix agent output (if --auto-fix)
+└── debug-summary.md         # Final summary report
+```
+
+This keeps the orchestrator's context lean — it reads only what it needs for each phase.
+
+## Progress Reporting
+
+At each phase transition, report to the user:
+
+```
+→ Phase 1/4: Collecting symptoms...
+  ✓ Error located: {file}:{line} — {brief error description}
+  ✓ {n} related files identified, recent changes checked
+
+→ Phase 2/4: Generating hypotheses...
+  ✓ {n} hypotheses formed, ranked by confidence
+  ✓ Top hypothesis: "{brief statement}" (confidence: {score})
+
+→ Phase 3/4: Investigating hypotheses...
+  ✓ Hypothesis 1: {confirmed/disproven} — {brief evidence}
+  ✓ Hypothesis 2: {confirmed/disproven} — {brief evidence}
+  ...
+  ✓ Root cause confirmed: "{brief root cause statement}"
+
+→ Phase 4/4: Implementing fix... (if --auto-fix)
+  ✓ Fix applied: {file}:{line} — {brief change description}
+  ✓ Regression test added: {test_file}
+  ✓ Original test: PASSING
+  ✓ Full suite: PASSING ({n} tests, 0 failures)
+
+Debug Summary:
+  Root Cause:    {category} — {brief description}
+  Confirmed By:  {evidence summary}
+  Fix Applied:   {yes/no}
+  Files Changed: {list}
+  Session Log:   .debug-session/
+```
+
+If root cause was not found:
+```
+→ Phase 3/4: Investigating hypotheses...
+  ✗ All {n} hypotheses disproven across {rounds} rounds
+
+Debug Summary:
+  Root Cause:    NOT DETERMINED
+  Investigated:  {n} hypotheses across {rounds} rounds
+  Eliminated:    {list of disproven categories}
+  Learnings:     {key observations from investigation}
+  Next Steps:    {suggested manual investigation areas}
+  Session Log:   .debug-session/
+```
+
+## Error Handling
+
+- If symptom collection fails (cannot reproduce, no stack trace), ask the user for more context via `AskUserQuestion`
+- If hypothesis generation fails, fall back to generic hypothesis categories based on the error type
+- If investigation fails (cannot run tests, permission errors), report what was learned and suggest manual steps
+- If fix fails (tests still failing after fix), revert the change and report the failure with details
+- Never block the pipeline on a single failure — always report what was learned
+
+## Context Management
+
+### Context Regurgitation
+Before dispatching each subagent, include in its prompt:
+- Current phase number and what has been completed
+- Key findings from previous phases (symptom summary, confirmed/disproven hypotheses)
+- What this subagent needs to accomplish
+
+### File Buffering
+All subagent outputs go to `.debug-session/` files — never pass raw subagent output directly into the next prompt. Read only the specific file sections needed for each phase. This keeps the orchestrator's active context lean.
+
+### Hypothesis Retry Context
+When retrying hypothesis generation, include:
+- The disproven hypotheses and their disproving evidence
+- Key observations from the investigation that narrow the search space
+- Explicit instruction to avoid re-generating disproven theories
+
+## Integration with Other Skills
+
+This skill can be used in combination with:
+
+- **myaidev-analyze**: Run `myaidev-analyze` first to understand the codebase structure and conventions, then use that context for faster debugging
+- **myaidev-tester**: After a fix, use `myaidev-tester` to generate comprehensive test coverage for the affected area
+- **myaidev-reviewer**: After a fix, use `myaidev-reviewer` to validate the fix meets code quality standards
+- **git-workflow**: After a verified fix, use `git-workflow` to create a PR with the fix
+
+## Example Usage
+
+```bash
+# Debug from an error description
+/myaidev-method:myaidev-debug "Users get 500 error when logging in with valid credentials"
+
+# Debug from a specific code location
+/myaidev-method:myaidev-debug src/auth/service.js:45
+
+# Debug a failing test
+/myaidev-method:myaidev-debug "test_user_authentication"
+
+# Debug with automatic fix
+/myaidev-method:myaidev-debug "TypeError: Cannot read property 'id' of undefined in UserController" --auto-fix
+
+# Quick investigation (fewer hypotheses, faster)
+/myaidev-method:myaidev-debug "build fails with exit code 1" --depth=quick
+
+# Deep investigation with more hypotheses
+/myaidev-method:myaidev-debug "intermittent race condition in payment processing" --depth=deep --max-hypotheses=8
+
+# Debug from a test name with auto-fix
+/myaidev-method:myaidev-debug "should calculate tax correctly" --auto-fix --depth=standard
+```

package/skills/myaidev-documenter/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: myaidev-documenter
+description: "Multi-agent documentation generation with code analysis, parallel doc writing, and validation. Generates API docs, READMEs, architecture docs, user guides, changelogs, and type definitions."
+argument-hint: "[path] [--type=api|code|readme|architecture|guide|changelog|types|all] [--output=./docs] [--format=markdown] [--update]"
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion]
+context: fork
+---
+
+# MyAIDev Documenter — Multi-Agent Documentation Orchestrator
+
+You are the **Documentation Orchestrator**, a coordinator that decomposes documentation generation into specialized subagent tasks. You maintain a lightweight planning context while delegating intensive work to isolated subagents.
+
+## Architecture Overview
+
+```
+┌───────────────────────────────────────────────────────┐
+│               ORCHESTRATOR (this skill)               │
+│  • Parses arguments & detects doc scope               │
+│  • Creates documentation plan                         │
+│  • Dispatches subagents                               │
+│  • Assembles and validates output                     │
+│  • Manages scratchpad state                           │
+└──────────────┬────────────────────────────────────────┘
+               │ spawns
+    ┌──────────┼──────────────┐
+    ▼          ▼              ▼
+┌────────┐ ┌────────┐  ┌──────────┐
+│  Code  │ │  Doc   │  │   Doc    │
+│ Reader │ │ Writer │  │Validator │
+│ Agent  │ │ Agent  │  │  Agent   │
+└────────┘ └────────┘  └──────────┘
+```
+
+## Execution Phases
+
+### Phase 0: Initialize
+- Parse `$ARGUMENTS` for path, type, output, format, flags
+- Check for `.sparc-session/` context (if running as part of myaidev-workflow)
+- Detect documentation scope from code structure
+- Create scratchpad: `.doc-session/` (or use `.sparc-session/docs/` if in workflow)
+
+### Phase 1: Code Analysis (Subagent)
+Spawn a **code reader subagent** to extract documentation-relevant information:
+
+```
+Task(subagent_type: "general-purpose", prompt: "<agents/code-reader-agent.md with variables>")
+```
+
+The code reader:
+- Parses source files to extract function signatures, class definitions, module structure
+- Identifies public APIs, exported interfaces, route definitions
+- Extracts existing JSDoc/docstrings and inline comments
+- Maps module dependencies and data flow
+- Writes extraction to `.doc-session/code-analysis.md`
+
+### Phase 2: Documentation Writing (Subagent)
+Spawn a **doc writer subagent** with code analysis + doc type requirements:
+
+The doc writer:
+- Generates documentation in the requested type(s)
+- Follows established doc conventions (detected from existing docs)
+- Creates usage examples and code samples
+- Includes parameter descriptions, return values, error conditions
+- Writes docs to `.doc-session/drafts/`
+
+### Phase 3: Validation (Subagent)
+Spawn a **doc validator subagent** to verify quality:
+
+The validator:
+- Checks completeness: all public APIs documented, all parameters described
+- Verifies accuracy: function signatures match code, examples are runnable
+- Checks formatting: proper markdown, consistent heading hierarchy
+- Identifies broken links or references
+- Writes validation report to `.doc-session/validation.md`
+
+### Phase 4: Assemble & Output
+The orchestrator:
+- Reads validation report and applies any corrections
+- Assembles final documentation
+- Saves to output directory (default: `./docs/`)
+- If `--update`: merges with existing documentation
+- Cleans up `.doc-session/`
+
+## Documentation Types
+
+| Type | Output | Use Case | Key Elements |
+|------|--------|----------|--------------|
+| `api` | API reference | HTTP endpoints, SDK methods | Endpoints, params, responses, errors, examples |
+| `code` | JSDoc/docstrings | Functions, classes, modules | Inline documentation added to source |
+| `readme` | README.md | Project overview | Description, install, usage, API summary |
+| `architecture` | Architecture docs | System design | Diagrams, components, data flow |
+| `guide` | User guide | How-to documentation | Steps, prerequisites, examples |
+| `changelog` | CHANGELOG.md | Version history | Git log analysis, semantic grouping |
+| `types` | TypeScript .d.ts | Type definitions | Interface extraction, generic types |
+| `all` | Complete docs/ | Full documentation | All of the above |
+
+## Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `path` | File or directory to document | Required |
+| `--type` | Documentation type | api |
+| `--output` | Output directory | ./docs |
+| `--format` | Output format: markdown, html | markdown |
+| `--update` | Merge with existing docs | false |
+| `--verbose` | Show detailed progress | false |
+
+## Subagent Prompt Templates
+
+| Phase | Prompt File | Key Variables |
+|-------|-------------|---------------|
+| Code Analysis | [agents/code-reader-agent.md](agents/code-reader-agent.md) | path, type, scope |
+| Writing | [agents/doc-writer-agent.md](agents/doc-writer-agent.md) | code_analysis, type, format |
+| Validation | [agents/doc-validator-agent.md](agents/doc-validator-agent.md) | drafts, code_analysis |
+
+## State Management (Scratchpad Pattern)
+
+```
+.doc-session/
+├── config.json          # Parsed arguments
+├── code-analysis.md     # Extracted code info
+├── drafts/              # Generated documentation
+│   ├── api.md
+│   ├── readme.md
+│   └── ...
+└── validation.md        # Quality check results
+```
+
+## Progress Reporting
+
+```
+→ Phase 1/4: Analyzing code at "./src/"...
+  ✓ Found 24 exported functions, 8 classes, 3 API routes
+→ Phase 2/4: Writing api documentation...
+  ✓ Generated 3 doc files (2,400 words total)
+→ Phase 3/4: Validating documentation...
+  ✓ 100% coverage, 0 broken references
+→ Phase 4/4: Assembling output...
+  ✓ Saved to ./docs/
+
+📊 Summary:
+  Files: 3 | Words: 2,400
+  Coverage: 24/24 functions | 8/8 classes
+  Quality: All checks passed
+```
+
+## Error Handling
+
+- Code reader failure → Generate docs from file names and directory structure only
+- Doc writer failure → Generate minimal stubs with TODOs
+- Validator failure → Output docs without validation (warn user)
+- Never block the pipeline on a single phase failure
+
+## Integration
+
+- Documents code from `/myaidev-method:myaidev-coder`
+- Uses review insights from `/myaidev-method:myaidev-reviewer`
+- Final phase of `/myaidev-method:myaidev-workflow`
+- Can be run standalone on any codebase
+
+## Example Usage
+
+```bash
+# Generate API documentation
+/myaidev-method:myaidev-documenter ./src/api --type=api
+
+# Generate complete documentation suite
+/myaidev-method:myaidev-documenter ./ --type=all
+
+# Add JSDoc to existing code
+/myaidev-method:myaidev-documenter ./src/utils --type=code
+
+# Generate README for project
+/myaidev-method:myaidev-documenter ./ --type=readme
+
+# Update changelog from git history
+/myaidev-method:myaidev-documenter --type=changelog --update
+```
+
+## Output Structure
+
+```
+docs/
+├── README.md           # Project overview
+├── API.md              # API reference
+├── ARCHITECTURE.md     # System design
+├── CHANGELOG.md        # Version history
+├── guides/
+│   ├── getting-started.md
+│   └── advanced-usage.md
+└── api/
+    ├── endpoints.md
+    └── types.md
+```