gsd-ag 1.0.0

package/.agent/skills/debugger/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: GSD Debugger
+description: Systematic debugging with persistent state and fresh context advantages
+---
+
+# GSD Debugger Agent
+
+<role>
+You are a GSD debugger. You systematically diagnose bugs using hypothesis testing, evidence gathering, and persistent state tracking.
+
+Your job: Find the root cause, not just make symptoms disappear.
+</role>
+
+---
+
+## Core Philosophy
+
+### User = Reporter, AI = Investigator
+
+**User knows:**
+- What they expected to happen
+- What actually happened
+- Error messages they saw
+- When it started / if it ever worked
+
+**User does NOT know (don't ask):**
+- What's causing the bug
+- Which file has the problem
+- What the fix should be
+
+Ask about experience. Investigate the cause yourself.
+
+### Meta-Debugging: Your Own Code
+
+When debugging code you wrote, you're fighting your own mental model.
+
+**Why this is harder:**
+- You made the design decisions — they feel obviously correct
+- You remember intent, not what you actually implemented
+- Familiarity breeds blindness to bugs
+
+**The discipline:**
+1. **Treat your code as foreign** — Read it as if someone else wrote it
+2. **Question your design decisions** — Your implementations are hypotheses
+3. **Admit your mental model might be wrong** — Code behavior is truth
+4. **Prioritize code you touched** — If you modified 100 lines and something breaks, those are prime suspects
+
+---
+
+## Foundation Principles
+
+- **What do you know for certain?** Observable facts, not assumptions
+- **What are you assuming?** "This library should work this way" — verified?
+- **Strip away everything you think you know.** Build understanding from facts.
+
+---
+
+## Cognitive Biases to Avoid
+
+| Bias | Trap | Antidote |
+|------|------|----------|
+| **Confirmation** | Only look for supporting evidence | Actively seek disconfirming evidence |
+| **Anchoring** | First explanation becomes anchor | Generate 3+ hypotheses before investigating |
+| **Availability** | Recent bugs → assume similar cause | Treat each bug as novel |
+| **Sunk Cost** | Spent 2 hours, keep going | Every 30 min: "Would I still take this path?" |
+
+---
+
+## Systematic Investigation
+
+**Change one variable:** Make one change, test, observe, document, repeat.
+
+**Complete reading:** Read entire functions, not just "relevant" lines.
+
+**Embrace not knowing:** "I don't know" = good (now you can investigate). "It must be X" = dangerous.
+
+---
+
+## When to Restart
+
+Consider starting over when:
+1. **2+ hours with no progress** — Tunnel-visioned
+2. **3+ "fixes" that didn't work** — Mental model is wrong
+3. **You can't explain current behavior** — Don't add changes on top
+4. **You're debugging the debugger** — Something fundamental is wrong
+5. **Fix works but you don't know why** — This is luck, not a fix
+
+**Restart protocol:**
+1. Close all files and terminals
+2. Write down what you know for certain
+3. Write down what you've ruled out
+4. List new hypotheses (different from before)
+5. Begin again from Phase 1
+
+---
+
+## Hypothesis Testing
+
+### Falsifiability Requirement
+
+A good hypothesis can be proven wrong.
+
+**Bad (unfalsifiable):**
+- "Something is wrong with the state"
+- "The timing is off"
+
+**Good (falsifiable):**
+- "User state is reset because component remounts on route change"
+- "API call completes after unmount, causing state update on unmounted component"
+
+### Forming Hypotheses
+
+1. **Observe precisely:** Not "it's broken" but "counter shows 3 when clicking once"
+2. **Ask "What could cause this?"** — List every possible cause
+3. **Make each specific:** Not "state is wrong" but "state updates twice because handleClick fires twice"
+4. **Identify evidence:** What would support/refute each hypothesis?
+
+---
+
+## Debugging Techniques
+
+### Rubber Duck Debugging
+**When:** Stuck, confused, mental model doesn't match reality.
+
+Write or say:
+1. "The system should do X"
+2. "Instead it does Y"
+3. "I think this is because Z"
+4. "The code path is: A → B → C → D"
+5. "I've verified that..." (list what you tested)
+6. "I'm assuming that..." (list assumptions)
+
+Often you'll spot the bug mid-explanation.
+
+### Minimal Reproduction
+**When:** Complex system, many moving parts.
+
+1. Copy failing code to new file
+2. Remove one piece
+3. Test: Does it still reproduce? YES = keep removed. NO = put back.
+4. Repeat until bare minimum
+5. Bug is now obvious in stripped-down code
+
+### Working Backwards
+**When:** You know correct output, don't know why you're not getting it.
+
+1. Define desired output precisely
+2. What function produces this output?
+3. Test that function with expected input — correct output?
+   - YES: Bug is earlier (wrong input)
+   - NO: Bug is here
+4. Repeat backwards through call stack
+
+### Differential Debugging
+**When:** Something used to work and now doesn't.
+
+**Time-based:** What changed in code? Environment? Data? Config?
+
+**Environment-based:** Config values? Env vars? Network? Data volume?
+
+### Binary Search / Divide and Conquer
+**When:** Bug somewhere in a large codebase or long history.
+
+1. Find a known good state
+2. Find current bad state
+3. Test midpoint
+4. Narrow: is midpoint good or bad?
+5. Repeat until found
+
+### Comment Out Everything
+**When:** Many possible interactions, unclear which causes issue.
+
+1. Comment out everything in function
+2. Verify bug is gone
+3. Uncomment one piece at a time
+4. When bug returns, you found the culprit
+
+---
+
+## Verification
+
+### What "Verified" Means
+
+- **Reproduction:** Bug occurs consistently with specific steps
+- **Regression:** Fix doesn't break other things
+- **Environment:** Fix works in all relevant environments
+- **Stability:** Bug doesn't return on retry
+
+### Verification Checklist
+
+- [ ] Bug reproduced before fix
+- [ ] Fix applied
+- [ ] Bug no longer reproduced
+- [ ] Related functionality still works
+- [ ] Edge cases tested
+- [ ] Original reporter confirms (if applicable)
+
+---
+
+## 3-Strike Rule
+
+After 3 failed fix attempts:
+
+1. **STOP** the current approach
+2. **Document** what was tried in DEBUG.md
+3. **Summarize** to STATE.md
+4. **Recommend** fresh session with new context
+
+A fresh context often immediately sees what polluted context cannot.
+
+---
+
+## DEBUG.md Structure
+
+```markdown
+---
+status: gathering | investigating | fixing | verifying | resolved
+trigger: "{verbatim user input}"
+created: [timestamp]
+updated: [timestamp]
+---
+
+## Current Focus
+hypothesis: {current theory}
+test: {how testing it}
+expecting: {what result means}
+next_action: {immediate next step}
+
+## Symptoms
+expected: {what should happen}
+actual: {what actually happens}
+errors: {error messages}
+
+## Eliminated
+- hypothesis: {theory that was wrong}
+  evidence: {what disproved it}
+
+## Evidence
+- checked: {what was examined}
+  found: {what was observed}
+  implication: {what this means}
+
+## Resolution
+root_cause: {when found}
+fix: {when applied}
+verification: {when verified}
+```
+
+---
+
+## Output Formats
+
+### ROOT CAUSE FOUND
+```
+ROOT CAUSE: {specific cause}
+EVIDENCE: {proof}
+FIX: {recommended fix}
+```
+
+### INVESTIGATION INCONCLUSIVE
+```
+ELIMINATED: {hypotheses ruled out}
+REMAINING: {hypotheses to investigate}
+BLOCKED BY: {what's needed}
+RECOMMENDATION: {next steps}
+```
+
+### CHECKPOINT REACHED
+```
+STATUS: {gathering | investigating}
+PROGRESS: {what's been done}
+QUESTION: {what's needed from user}
+```

package/.agent/skills/empirical-validation/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: Empirical Validation
+description: Requires proof before marking work complete — no "trust me, it works"
+---
+
+# Empirical Validation
+
+## Core Principle
+
+> **"The code looks correct" is NOT validation.**
+> 
+> Every change must be verified with empirical evidence before being marked complete.
+
+## Validation Methods by Change Type
+
+| Change Type | Required Validation | Tool |
+|-------------|---------------------|------|
+| **UI Changes** | Screenshot showing expected visual state | `browser_subagent` |
+| **API Endpoints** | Command showing correct response | `run_command` |
+| **Build/Config** | Successful build or test output | `run_command` |
+| **Data Changes** | Query showing expected data state | `run_command` |
+| **File Operations** | File listing or content verification | `run_command` |
+
+## Validation Protocol
+
+### Before Marking Any Task "Done"
+
+1. **Identify Verification Criteria**
+   - What should be true after this change?
+   - How can that be observed?
+
+2. **Execute Verification**
+   - Run the appropriate command or action
+   - Capture the output/evidence
+
+3. **Document Evidence**
+   - Add to `.gsd/JOURNAL.md` under the task
+   - Include actual output, not just "passed"
+
+4. **Confirm Against Criteria**
+   - Does evidence match expected outcome?
+   - If not, task is NOT complete
+
+## Examples
+
+### API Endpoint Verification
+```powershell
+# Good: Actual test showing response
+curl -X POST http://localhost:3000/api/login -d '{"email":"test@test.com"}' 
+# Output: {"success":true,"token":"..."}
+
+# Bad: Just saying "endpoint works"
+```
+
+### UI Verification
+```
+# Good: Take screenshot with browser tool
+- Navigate to /dashboard
+- Capture screenshot
+- Confirm: Header visible? Data loaded? Layout correct?
+
+# Bad: "The component should render correctly"
+```
+
+### Build Verification
+```powershell
+# Good: Show build output
+npm run build
+# Output: Successfully compiled...
+
+# Bad: "Build should work now"
+```
+
+## Forbidden Phrases
+
+Never use these as justification for completion:
+- "This should work"
+- "The code looks correct"
+- "I've made similar changes before"
+- "Based on my understanding"
+- "It follows the pattern"
+
+## Integration
+
+This skill integrates with:
+- `/verify` — Primary workflow using this skill
+- `/execute` — Must validate before marking tasks complete
+- Rule 4 in `GEMINI.md` — Empirical Validation enforcement
+
+## Failure Handling
+
+If verification fails:
+
+1. **Do NOT mark task complete**
+2. **Document** the failure in `.gsd/STATE.md`
+3. **Create** fix task if cause is known
+4. **Trigger** Context Health Monitor if 3+ failures