@jokerized/getresearchdone 0.4.1

package/commands/debug.md

@@ -0,0 +1,372 @@
+---
+description: Systematic debugging with persistent state across context resets
+argument-hint: [bug description or session ID to resume]
+---
+
+<purpose>
+Systematic debugging with persistent state across context resets. Manages debug sessions via .planning/debug/ files that track hypotheses, evidence, and resolutions. Spawns grd-debugger agent for investigation.
+
+User reports issue, Claude investigates autonomously. Debug state persists across /clear for long investigations.
+</purpose>
+
+<paths>
+DEBUG_DIR=.planning/debug
+DEBUG_RESOLVED_DIR=.planning/debug/resolved
+
+Debug files use the `.planning/debug/` path.
+</paths>
+
+<core_principle>
+**Scientific method for debugging.**
+
+1. Observe symptoms precisely
+2. Form falsifiable hypotheses
+3. Design experiments to test them
+4. Record evidence
+5. Eliminate failed hypotheses
+6. Confirm root cause with evidence
+7. Apply and verify fix
+
+The debug file IS the brain. Claude should resume perfectly from any /clear point.
+</core_principle>
+
+<process>
+
+<step name="initialize" priority="first">
+Load debug context:
+
+```bash
+INIT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js state load)
+DEBUGGER_MODEL=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js resolve-model grd-debugger --raw)
+```
+
+Parse: `commit_docs`, `autonomous_mode`.
+</step>
+
+<step name="check_active_sessions">
+**First: Check for active debug sessions**
+
+```bash
+ls .planning/debug/*.md 2>/dev/null | grep -v resolved
+```
+
+**If active sessions exist AND no $ARGUMENTS provided:**
+
+Read each file's frontmatter (status, trigger) and Current Focus section.
+
+Display:
+
+```
+## Active Debug Sessions
+
+| # | Issue | Status | Current Hypothesis | Evidence |
+|---|-------|--------|-------------------|----------|
+| 1 | auth-screen-dark | investigating | Background CSS override | 3 findings |
+| 2 | model-nan-loss | gathering | [awaiting symptoms] | 0 findings |
+
+Reply with a number to resume, or describe a new issue to start.
+```
+
+Wait for user response.
+
+- If number → Load that file, spawn grd-debugger with resume context
+- If text → Treat as new issue, go to `create_session`
+
+**If active sessions AND $ARGUMENTS provided:**
+- Start new session with $ARGUMENTS as the issue description
+
+**If no active sessions AND no $ARGUMENTS:**
+```
+No active debug sessions. Describe the issue to start debugging.
+```
+
+**If no active sessions AND $ARGUMENTS provided:**
+- Continue to `create_session`
+</step>
+
+<step name="create_session">
+**Create debug session and spawn debugger:**
+
+Generate slug from user input (lowercase, hyphens, max 30 chars).
+
+```bash
+mkdir -p .planning/debug
+```
+
+Spawn grd-debugger agent:
+
+```
+Task(
+  prompt="""
+<objective>
+Investigate issue reported by user.
+
+**User report:** {$ARGUMENTS or user input}
+</objective>
+
+<mode>
+symptoms_prefilled: false
+goal: find_and_fix
+</mode>
+
+<debug_file>
+Create: .planning/debug/{slug}.md
+</debug_file>
+""",
+  subagent_type="grd:grd-debugger",
+  model="{debugger_model}",
+  description="Debug: {slug}"
+)
+```
+
+The grd-debugger agent will:
+1. Create the debug file immediately
+2. Gather symptoms through questioning (if not pre-filled)
+3. Investigate autonomously
+4. Return ROOT CAUSE FOUND, DEBUG COMPLETE, CHECKPOINT REACHED, or INVESTIGATION INCONCLUSIVE
+</step>
+
+<step name="resume_session">
+**Resume an existing debug session:**
+
+Read the debug file to get current state.
+
+Spawn grd-debugger with resume context:
+
+```
+Task(
+  prompt="""
+<objective>
+Continue debugging {slug}. Evidence is in the debug file.
+</objective>
+
+<prior_state>
+Debug file: @.planning/debug/{slug}.md
+</prior_state>
+
+<mode>
+goal: find_and_fix
+</mode>
+""",
+  subagent_type="grd:grd-debugger",
+  model="{debugger_model}",
+  description="Resume debug: {slug}"
+)
+```
+</step>
+
+<step name="handle_checkpoint">
+**Handle checkpoint from debugger agent:**
+
+When grd-debugger returns CHECKPOINT REACHED:
+
+Display the checkpoint to user:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► DEBUG CHECKPOINT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Issue:** {slug}
+**Type:** {human-verify | human-action | decision}
+**Progress:** {evidence_count} findings, {eliminated_count} hypotheses eliminated
+
+{checkpoint details from agent}
+
+──────────────────────────────────────────────────────
+→ {what's needed from user}
+──────────────────────────────────────────────────────
+```
+
+Wait for user response.
+
+Spawn continuation with user's response:
+
+```
+Task(
+  prompt="""
+<objective>
+Continue debugging {slug}. Evidence is in the debug file.
+</objective>
+
+<prior_state>
+Debug file: @.planning/debug/{slug}.md
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+
+<mode>
+goal: find_and_fix
+</mode>
+""",
+  subagent_type="grd:grd-debugger",
+  model="{debugger_model}",
+  description="Continue debug: {slug}"
+)
+```
+</step>
+
+<step name="handle_completion">
+**Handle completed debug session:**
+
+When grd-debugger returns DEBUG COMPLETE:
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► DEBUG RESOLVED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Issue:** {slug}
+**Root Cause:** {root_cause}
+**Fix Applied:** {fix description}
+**Files Changed:** {files list}
+**Verification:** {how verified}
+
+Debug session archived to .planning/debug/resolved/{slug}.md
+
+───────────────────────────────────────────────────────────────
+
+## Next Up
+
+- `/grd:verify-work {phase}` — Run full UAT
+- `/grd:execute-phase {phase}` — Continue phase execution
+- `/grd:debug` — Start another debug session
+
+───────────────────────────────────────────────────────────────
+```
+
+When grd-debugger returns INVESTIGATION INCONCLUSIVE:
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► DEBUG INCONCLUSIVE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Issue:** {slug}
+**What was checked:** {areas examined}
+**Hypotheses eliminated:** {count}
+**Remaining possibilities:**
+{list from agent return}
+
+Debug session saved to .planning/debug/{slug}.md
+
+Options:
+1. Resume investigation (fresh context, same evidence)
+2. Provide additional context (describe what you know)
+3. Abandon session
+```
+
+Wait for user response.
+</step>
+
+</process>
+
+<debug_file_template>
+Template for `.planning/debug/{slug}.md`:
+
+```markdown
+---
+status: gathering | investigating | fixing | verifying | resolved
+trigger: "[verbatim user input]"
+created: [ISO timestamp]
+updated: [ISO timestamp]
+---
+
+## Current Focus
+<!-- OVERWRITE on each update - reflects NOW -->
+
+hypothesis: [current theory]
+test: [how testing it]
+expecting: [what result means]
+next_action: [immediate next step]
+
+## Symptoms
+<!-- Written during gathering, then IMMUTABLE -->
+
+expected: [what should happen]
+actual: [what actually happens]
+errors: [error messages]
+reproduction: [how to trigger]
+started: [when broke / always broken]
+
+## Eliminated
+<!-- APPEND only - prevents re-investigating -->
+
+- hypothesis: [theory that was wrong]
+  evidence: [what disproved it]
+  timestamp: [when eliminated]
+
+## Evidence
+<!-- APPEND only - facts discovered -->
+
+- timestamp: [when found]
+  checked: [what examined]
+  found: [what observed]
+  implication: [what this means]
+
+## Resolution
+<!-- OVERWRITE as understanding evolves -->
+
+root_cause: [empty until found]
+fix: [empty until applied]
+verification: [empty until verified]
+files_changed: []
+```
+</debug_file_template>
+
+<session_management>
+
+## Session Lifecycle
+
+| Event | Action |
+|-------|--------|
+| `/grd:debug "issue description"` | Create new session, spawn debugger |
+| `/grd:debug` (with active sessions) | List sessions, offer resume |
+| `/grd:debug` (no sessions, no args) | Prompt for issue description |
+| Agent returns CHECKPOINT | Present to user, spawn continuation |
+| Agent returns DEBUG COMPLETE | Show resolution, archive session |
+| Agent returns INCONCLUSIVE | Offer resume, context, or abandon |
+| `/clear` during debug | Session state preserved in file |
+
+## File State Guarantees
+
+The debug file always reflects the latest state:
+- **Current Focus** shows what was happening when last updated
+- **Eliminated** prevents re-investigating dead ends
+- **Evidence** accumulates findings
+- Any Claude instance can resume from the file alone
+
+</session_management>
+
+<failure_handling>
+
+**Agent fails or errors:**
+- Debug file preserves progress up to last update
+- Resume with `/grd:debug` — will detect existing session
+- Evidence and eliminated hypotheses are never lost
+
+**Agent times out:**
+- Check .planning/debug/{slug}.md for partial progress
+- Resume picks up from Current Focus
+
+**User /clear during investigation:**
+- File persists
+- Next `/grd:debug` detects active session
+- Offers to resume from last recorded state
+
+</failure_handling>
+
+<success_criteria>
+- [ ] Active sessions detected and offered for resume
+- [ ] New sessions create debug file immediately
+- [ ] grd-debugger agent spawned with appropriate context
+- [ ] Checkpoints presented to user and responses forwarded
+- [ ] Completed sessions archived to resolved/
+- [ ] Inconclusive sessions offer resume options
+- [ ] State persists across /clear boundaries
+- [ ] All commands reference grd-tools.js via ${CLAUDE_PLUGIN_ROOT}
+</success_criteria>

package/commands/deep-dive.md

@@ -0,0 +1,288 @@
+---
+description: Deep analysis of a specific paper — method, code, limitations, production considerations
+argument-hint: <paper title, URL, or arXiv ID>
+---
+
+<purpose>
+Deep analysis of a specific paper — method architecture, code reproduction, limitations,
+and production considerations. Creates a structured deep-dive document that feeds into
+feasibility analysis and implementation planning. This is the microscope after the
+survey's telescope.
+</purpose>
+
+<context>
+CLAUDE.md rules: @CLAUDE.md
+
+**Research directory structure** (paths resolved via init):
+- `${research_dir}/deep-dives/{PAPER-SLUG}.md` — individual paper analysis
+- `${research_dir}/PAPERS.md` — master index of all reviewed papers
+- `${research_dir}/LANDSCAPE.md` — survey landscape (may reference this paper)
+- `.planning/config.json` — GRD configuration
+
+**Agent available:**
+- `grd-deep-diver` — specialized paper analysis agent with web search, code reading, critique
+</context>
+
+<process>
+
+## Step 0: INITIALIZE — Parse Paper Reference
+
+0. **Run initialization**:
+   ```bash
+   INIT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js init deep-dive "$PAPER_REF")
+   ```
+   Parse JSON for: `research_dir`, `landscape_exists`, `papers_exists`, `deep_dives`, `researcher_model`, `autonomous_mode`, `research_gates`.
+
+1. **Parse arguments**: Extract paper reference from `$ARGUMENTS`
+   - If arXiv URL (e.g., `arxiv.org/abs/2301.12345`): extract ID, fetch metadata
+   - If paper title: search for canonical reference
+   - If Semantic Scholar / DOI URL: extract metadata
+   - If empty: check LANDSCAPE.md for top recommendation, ASK user to confirm
+
+2. **Normalize paper reference**:
+   ```
+   PAPER_TITLE: {full title}
+   PAPER_AUTHORS: {first author et al.}
+   PAPER_YEAR: {year}
+   PAPER_URL: {canonical URL}
+   PAPER_SLUG: {kebab-case-short-name}  (for filename)
+   ```
+
+3. **Check for existing deep-dive**:
+   - Look for `${research_dir}/deep-dives/{PAPER-SLUG}.md`
+   - If exists: load previous analysis, note it will be updated/extended
+   - If not: this is a fresh analysis
+
+4. **Ensure directory exists**:
+   ```bash
+   mkdir -p ${research_dir}/deep-dives
+   ```
+
+5. **Load context from LANDSCAPE.md** (if available):
+   - Find this paper's entry in the landscape
+   - Extract related methods, benchmarks, known metrics
+
+6. **Read config**: Check `research_gates.deep_dive_approval`
+
+**STEP_0_CHECKPOINT:**
+- [ ] Paper reference normalized with title, authors, URL
+- [ ] Paper slug generated for filename
+- [ ] Existing analysis checked
+- [ ] LANDSCAPE.md context loaded
+
+---
+
+## Step 1: DISPLAY BANNER
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  GRD >>> DEEP DIVE                                          ║
+║                                                             ║
+║  Paper: {paper_title}                                       ║
+║  Authors: {authors}                                         ║
+║  Year: {year}                                               ║
+║  URL: {url}                                                 ║
+║  Status: {fresh analysis | updating existing}               ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Step 2: SPAWN DEEP-DIVER AGENT
+
+**Launch `grd-deep-diver` agent via Task tool:**
+
+Use Task tool with `subagent_type="grd:grd-deep-diver"`:
+
+```
+Deep-dive analysis of paper: {PAPER_TITLE}
+
+PATHS:
+research_dir: ${research_dir}
+
+URL: {PAPER_URL}
+Authors: {PAPER_AUTHORS}, {PAPER_YEAR}
+
+LANDSCAPE CONTEXT:
+{Related methods and benchmarks from LANDSCAPE.md, or "No landscape yet"}
+
+EXISTING ANALYSIS (if updating):
+{Previous deep-dive content, or "Fresh analysis"}
+
+ANALYZE THE FOLLOWING DIMENSIONS:
+
+1. METHOD ARCHITECTURE:
+   - Core algorithm / model architecture
+   - Key innovations vs prior work
+   - Mathematical formulation (simplified)
+   - Training procedure and loss functions
+   - Inference pipeline
+
+2. REPORTED RESULTS:
+   - Benchmarks used and metrics reported
+   - Comparison with baselines (table format)
+   - Ablation study findings
+   - Statistical significance (if reported)
+
+3. CODE AVAILABILITY:
+   - Official implementation: URL, language, framework, license
+   - Third-party implementations: quality, maintenance status
+   - Reproduction difficulty estimate (1-5 scale)
+   - Key dependencies and version requirements
+
+4. LIMITATIONS AND ASSUMPTIONS:
+   - Explicitly stated limitations
+   - Implicit assumptions (data distribution, compute, etc.)
+   - Failure modes mentioned or inferable
+   - Scalability concerns
+
+5. PRODUCTION CONSIDERATIONS:
+   - Inference latency characteristics
+   - Memory/compute requirements
+   - Data requirements for fine-tuning
+   - Serving architecture implications
+   - Licensing constraints
+
+6. VERDICT:
+   - ADOPT: ready for production use
+   - TRIAL: promising, needs evaluation in our context
+   - ASSESS: interesting but significant unknowns
+   - HOLD: not suitable for current needs (explain why)
+
+   Provide confidence level (HIGH/MEDIUM/LOW) and rationale.
+
+OUTPUT FORMAT:
+Return structured markdown with all 6 sections, tables where appropriate,
+and a clear verdict section at the top for quick scanning.
+```
+
+**STEP_2_CHECKPOINT:**
+- [ ] Deep-diver agent launched with full context
+- [ ] Agent returned structured analysis
+- [ ] All 6 dimensions covered
+
+---
+
+## Step 3: VALIDATE AND ENRICH RESULTS
+
+1. **Validate completeness**: Check all 6 sections are present and substantive
+2. **Cross-reference with LANDSCAPE.md**:
+   - Verify reported metrics match landscape data
+   - Flag any discrepancies
+3. **Enrich with metadata**:
+   - Add analysis date
+   - Add analyst note on confidence
+   - Add links to related deep-dives if they exist
+
+---
+
+## Step 4: DISPLAY VERDICT
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  DEEP DIVE VERDICT                                          ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                             ║
+║  Paper: {paper_title_short}                                 ║
+║  Verdict: {ADOPT | TRIAL | ASSESS | HOLD}                  ║
+║  Confidence: {HIGH | MEDIUM | LOW}                          ║
+║                                                             ║
+║  Key strengths:                                             ║
+║    + {strength_1}                                           ║
+║    + {strength_2}                                           ║
+║                                                             ║
+║  Key concerns:                                              ║
+║    - {concern_1}                                            ║
+║    - {concern_2}                                            ║
+║                                                             ║
+║  Code: {available | partial | none}                         ║
+║  Reproduction: {1-5}/5 difficulty                           ║
+║                                                             ║
+║  Production readiness: {ready | needs-work | research-only} ║
+║                                                             ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Step 5: WRITE DEEP-DIVE FILE
+
+1. **Write deep-dive document**:
+   - Path: `${research_dir}/deep-dives/{PAPER-SLUG}.md`
+   - Include YAML frontmatter with metadata:
+     ```yaml
+     ---
+     paper: {title}
+     authors: {authors}
+     year: {year}
+     url: {url}
+     verdict: {ADOPT|TRIAL|ASSESS|HOLD}
+     confidence: {HIGH|MEDIUM|LOW}
+     analyzed: {YYYY-MM-DD}
+     ---
+     ```
+
+2. **Update PAPERS.md index**:
+   - If PAPERS.md exists: update this paper's row, set status to `deep-dived`
+   - If PAPERS.md does not exist: create it with header and this paper's entry
+   - Format: `| title | authors | year | verdict | confidence | deep-dive-link |`
+
+3. **Update LANDSCAPE.md** (if paper is referenced there):
+   - Add verdict annotation next to the method entry
+   - Add `[deep-dive](${research_dir}/deep-dives/{PAPER-SLUG}.md)` link
+
+---
+
+## Step 6: COMMIT
+
+1. **Stage files**:
+   ```bash
+   git add ${research_dir}/deep-dives/{PAPER-SLUG}.md
+   git add ${research_dir}/PAPERS.md
+   git add ${research_dir}/LANDSCAPE.md 2>/dev/null
+   ```
+
+2. **Commit**:
+   ```bash
+   git commit -m "research: deep-dive {paper_title_short} — verdict: {verdict}"
+   ```
+
+---
+
+## Step 7: ROUTE NEXT ACTION
+
+| Verdict | Suggestion |
+|---------|------------|
+| ADOPT | `/grd:feasibility {paper}` — analyze production gap |
+| TRIAL | `/grd:eval-plan` — design evaluation to test in our context |
+| ASSESS | `/grd:compare-methods` — compare with alternatives |
+| HOLD | `/grd:survey {refined_topic}` — look for better options |
+
+</process>
+
+<output>
+**FILES_WRITTEN:**
+- `${research_dir}/deep-dives/{PAPER-SLUG}.md` — full paper analysis
+- `${research_dir}/PAPERS.md` — updated paper index
+- `${research_dir}/LANDSCAPE.md` — annotated with verdict (if applicable)
+
+**DISPLAY**: Verdict summary with strengths, concerns, and next-step routing
+
+**GIT**: Committed with message: `research: deep-dive {paper} — verdict: {verdict}`
+</output>
+
+<error_handling>
+- **Paper not found**: Ask user to provide URL or clarify title, search with alternate terms
+- **No code available**: Note in analysis, increase reproduction difficulty score
+- **Agent returns incomplete analysis**: Fill gaps with "UNKNOWN — needs manual review" markers
+- **PAPERS.md format corrupted**: Back up and recreate from deep-dives directory listing
+- **Conflicting metrics**: Flag discrepancy explicitly, note both sources
+</error_handling>
+
+<success_criteria>
+- Deep-dive covers all 6 dimensions with substantive analysis
+- Verdict is clear with confidence level and rationale
+- Production considerations are specific (not generic)
+- PAPERS.md index is consistent with deep-dives directory
+- Analysis is traceable to paper content (not hallucinated claims)
+</success_criteria>