@jokerized/getresearchdone 0.4.1

package/commands/insert-phase.md

@@ -0,0 +1,113 @@
+---
+description: Insert a decimal phase for urgent work between existing phases
+argument-hint: <after phase number> <phase name and goal>
+---
+
+<purpose>
+Insert a decimal phase for urgent work discovered mid-milestone between existing integer phases. Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions without renumbering the entire roadmap.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- First argument: integer phase number to insert after
+- Remaining arguments: phase description
+
+Example: `/grd:insert-phase 72 Fix critical auth bug`
+-> after = 72, description = "Fix critical auth bug"
+
+If arguments missing:
+```
+ERROR: Both phase number and description required
+Usage: /grd:insert-phase <after> <description>
+Example: /grd:insert-phase 72 Fix critical auth bug
+```
+Exit.
+</step>
+
+<step name="init_context">
+```bash
+INIT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js init phase-op "${after_phase}")
+```
+
+Parse JSON for: `roadmap_exists`, `phases_dir`, `commit_docs`.
+
+Check `roadmap_exists` from init JSON. If false: Error and exit.
+</step>
+
+<step name="insert_phase">
+```bash
+RESULT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js phase insert "${after_phase}" "${description}")
+```
+
+Extract from result: `phase_number`, `after_phase`, `name`, `slug`, `directory`.
+</step>
+
+<step name="update_project_state">
+Update STATE.md under "### Roadmap Evolution":
+```
+- Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)
+```
+</step>
+
+<step name="reschedule_check">
+If `schedule_affected` is true in the result:
+
+1. Check tracker config:
+```bash
+TRACKER_CONFIG=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker get-config --raw)
+```
+
+2. If `provider` is `"mcp-atlassian"` and `auto_sync` is true:
+   - Run reschedule automatically:
+   ```bash
+   OPS=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js tracker prepare-reschedule --raw)
+   ```
+   - Parse `start_date_field` and `operations` from JSON
+   - For each operation with `action: "update"`: call MCP tool `update_issue` with `issue_key` and `additional_fields: {[start_date_field]: start_date, "duedate": due_date}`
+   - Display count of updated issues
+
+3. If `provider` is `"mcp-atlassian"` but `auto_sync` is false:
+   - Notify: `Schedule affected — inserted phase shifts subsequent dates. Run /grd:sync reschedule to update Jira dates.`
+
+4. Otherwise: skip (no tracker or GitHub provider — dates not applicable).
+</step>
+
+<step name="completion">
+```
+Phase {decimal_phase} inserted after Phase {after_phase}:
+- Description: {description}
+- Directory: ${phases_dir}/{decimal-phase}-{slug}/
+- Duration: 3d (default for insertions — edit in ROADMAP.md to adjust)
+- Status: Not planned yet
+- Marker: (INSERTED) - indicates urgent work
+{If reschedule ran: "- Jira dates updated: {count} issues rescheduled"}
+
+---
+
+## Next Up
+
+**Phase {decimal_phase}: {description}** -- urgent insertion
+
+`/grd:plan-phase {decimal_phase}`
+
+<sub>`/clear` first -> fresh context window</sub>
+
+---
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] `grd-tools phase insert` executed successfully
+- [ ] Phase directory created
+- [ ] Roadmap updated with new phase entry (includes "(INSERTED)" marker)
+- [ ] STATE.md updated with roadmap evolution note
+- [ ] User informed of next steps and dependency implications
+</success_criteria>

package/commands/iterate.md

@@ -0,0 +1,327 @@
+---
+description: Trigger iteration loop — re-evaluate, re-survey, re-plan based on eval results not meeting targets
+argument-hint: <phase number or name>
+---
+
+<purpose>
+Trigger iteration loop when evaluation results do not meet targets. Re-evaluates the
+situation, identifies which metrics are below target and why, then offers structured
+options: survey alternatives, adjust approach, adjust targets, or skip. Records all
+iterations in EVAL.md history and updates KNOWHOW.md with failure analysis and
+next-approach rationale.
+</purpose>
+
+<context>
+CLAUDE.md rules: @CLAUDE.md
+
+**Project structure** (paths resolved via init):
+- `${phase_dir}/EVAL.md` — evaluation results with targets
+- `${phase_dir}/PLAN.md` — current phase plan
+- `.planning/KNOWHOW.md` — accumulated engineering knowledge
+- `.planning/ROADMAP.md` — project roadmap
+- `${research_dir}/LANDSCAPE.md` — research landscape
+- `.planning/BENCHMARKS.md` — historical benchmark data
+- `.planning/config.json` — GRD configuration (autonomous_mode)
+
+**This workflow does NOT spawn a dedicated agent.** It orchestrates decisions using
+existing data and delegates to other GRD workflows as needed.
+</context>
+
+<process>
+
+## Step 0: INITIALIZE — Load Evaluation State
+
+0. **Run initialization**:
+   ```bash
+   INIT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js init iterate "$PHASE")
+   ```
+   Parse JSON for: `research_dir`, `phases_dir`, `phase_dir` (resolve from phases_dir + phase number), `landscape_exists`, `knowhow_exists`, `baseline_exists`, `autonomous_mode`.
+
+1. **Parse arguments**: Extract phase identifier from `$ARGUMENTS`
+   - If phase number: resolve to `${phases_dir}/{N}-{name}/`
+   - If empty: detect phase with most recent EVAL.md results below target
+   - Validate phase directory and EVAL.md exist
+
+2. **Load EVAL.md results**:
+   - Parse the most recent `## Results` section
+   - Extract per-metric results: `{metric, baseline, target, result, status}`
+   - Identify metrics with status = MISS (below target)
+   - Load `## History` section for iteration count
+
+3. **Load supporting context**:
+   - PLAN.md — current approach being used
+   - CONTEXT.md — user decisions and constraints for this phase
+   - KNOWHOW.md — any prior failure learnings
+   - LANDSCAPE.md — alternative methods available
+   - BENCHMARKS.md — trend data across iterations
+
+4. **Compute iteration number**:
+   - Count entries in EVAL.md History section
+   - Current iteration = previous count + 1
+
+**STEP_0_CHECKPOINT:**
+- [ ] Phase identified with EVAL.md results
+- [ ] Below-target metrics identified
+- [ ] Iteration number computed
+- [ ] Supporting context loaded
+
+---
+
+## Step 1: DISPLAY ITERATION TRIGGER
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  GRD >>> ITERATION TRIGGERED                                ║
+║                                                             ║
+║  Phase: {N} — {phase_name}                                  ║
+║  Iteration: #{iteration_number}                             ║
+║                                                             ║
+║  Metrics below target:                                      ║
+║    {metric_1}: {actual} vs target {target} (gap: {gap})     ║
+║    {metric_2}: {actual} vs target {target} (gap: {gap})     ║
+║                                                             ║
+║  Metrics meeting target:                                    ║
+║    {metric_3}: {actual} >= {target}  OK                     ║
+║                                                             ║
+║  Trend: {improving | stagnant | regressing}                 ║
+║                                                             ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Step 2: ANALYZE FAILURE
+
+Using extended thinking, analyze why metrics fell short:
+
+1. **Gap characterization**:
+   - For each below-target metric:
+     - Gap magnitude: `|target - actual| / |target - baseline|` (% of improvement missing)
+     - Trend direction: improving, flat, or regressing across iterations?
+     - Correlation: do failures cluster (e.g., all accuracy metrics fail together)?
+
+2. **Root cause hypothesis**:
+   - Is the approach fundamentally limited? (architectural ceiling)
+   - Is the implementation incomplete? (more engineering needed)
+   - Is the data insufficient? (quality/quantity issue)
+   - Are the targets unrealistic? (SOTA gap too large for one phase)
+   - Is there a bug masking real performance? (measurement issue)
+
+3. **Effort-to-close estimate**:
+   - For each gap: estimated effort to close with current approach
+   - Diminishing returns analysis: are we on a plateau?
+
+```
+FAILURE ANALYSIS:
+
+  Root cause hypothesis: {hypothesis}
+  Confidence: {HIGH | MEDIUM | LOW}
+  Evidence: {what supports this hypothesis}
+
+  Gap closure estimate:
+    {metric_1}: {effort} to close {gap_pct}% gap
+    {metric_2}: {effort} to close {gap_pct}% gap
+
+  Plateau detection: {yes/no — are improvements flattening?}
+```
+
+---
+
+## Step 3: PRESENT OPTIONS
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ITERATION OPTIONS                                          ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                             ║
+║  a) SURVEY ALTERNATIVES                                     ║
+║     Run /grd:survey with refined topic based on failure     ║
+║     Then re-plan phase with new approach                    ║
+║     Best when: current approach has hit its ceiling         ║
+║                                                             ║
+║  b) ADJUST APPROACH                                         ║
+║     Modify current plan based on failure analysis           ║
+║     Keep same method, change implementation strategy        ║
+║     Best when: approach is sound but execution needs tuning ║
+║                                                             ║
+║  c) ADJUST TARGETS                                          ║
+║     Lower targets if they were unrealistic                  ║
+║     Document justification for target change                ║
+║     Best when: targets exceed SOTA or phase scope           ║
+║                                                             ║
+║  d) SKIP                                                    ║
+║     Accept current results and move forward                 ║
+║     Document decision to accept sub-target results          ║
+║     Best when: results are "good enough" for product goals  ║
+║                                                             ║
+║  Recommendation: {a|b|c|d} — {rationale}                   ║
+║                                                             ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+**In autonomous mode**: Execute the recommendation automatically. Log the decision.
+
+**In interactive mode**: Wait for user selection.
+
+---
+
+## Step 4: EXECUTE SELECTED OPTION
+
+### Option A: SURVEY ALTERNATIVES
+
+1. **Derive refined survey topic** from failure analysis:
+   - Current approach: {method}
+   - Failure mode: {what went wrong}
+   - Refined topic: "{original_topic} alternatives that address {failure_mode}"
+
+2. **Execute**: Trigger `/grd:survey {refined_topic}`
+
+3. **After survey completes**:
+   - Compare new methods against current approach
+   - If better candidate found: update PLAN.md with new approach
+   - Re-execute phase with new plan
+
+4. **Record in EVAL.md History**:
+   ```
+   | {date} | {iter} | SURVEY_ALT | Surveyed alternatives, pivoting to {new_method} |
+   ```
+
+### Option B: ADJUST APPROACH
+
+1. **Identify specific adjustments**:
+   - Hyperparameter changes
+   - Data preprocessing modifications
+   - Architecture tweaks within same method
+   - Training procedure changes
+
+2. **Update PLAN.md** with adjustments:
+   - Document what changed and why
+   - Mark adjusted tasks
+
+3. **Re-execute modified plan** (or suggest `/grd:execute-phase`)
+
+4. **Record in EVAL.md History**:
+   ```
+   | {date} | {iter} | ADJUST_APPROACH | Modified: {what_changed} |
+   ```
+
+### Option C: ADJUST TARGETS
+
+1. **For each below-target metric**:
+   - Propose new target with justification
+   - New target must be above baseline (no regression allowed)
+   - Reference SOTA to show target is realistic
+
+2. **Update EVAL.md** target values:
+   - Original target preserved in history
+   - New target annotated with justification
+
+3. **Record in EVAL.md History**:
+   ```
+   | {date} | {iter} | ADJUST_TARGET | {metric}: {old_target} -> {new_target} |
+   ```
+
+### Option D: SKIP
+
+1. **Document acceptance decision**:
+   - Which metrics are below target
+   - Why results are acceptable
+   - Impact on downstream phases
+
+2. **Record in EVAL.md History**:
+   ```
+   | {date} | {iter} | SKIP | Accepted {metric} at {value} vs target {target} |
+   ```
+
+3. **Update ROADMAP.md**: Mark phase as complete-with-caveats
+
+---
+
+## Step 5: UPDATE KNOWHOW.md
+
+Regardless of option chosen, append failure learnings:
+
+```markdown
+## Iteration {N} — Phase {phase} ({date})
+
+**What failed**: {metric} at {value} vs target {target}
+**Root cause**: {hypothesis}
+**Action taken**: {option chosen and details}
+**Key learning**: {what we now know that we did not before}
+**Next approach**: {what will be different next time}
+```
+
+This section is critical — it prevents repeating the same mistakes.
+
+---
+
+## Step 6: COMMIT
+
+```bash
+git add ${phase_dir}/*-EVAL.md
+git add ${phase_dir}/*-PLAN.md 2>/dev/null
+git add .planning/KNOWHOW.md
+git add .planning/ROADMAP.md 2>/dev/null
+git commit -m "iterate: phase {N} iter #{iteration} — {option_chosen}"
+```
+
+---
+
+## Step 7: GUARD AGAINST INFINITE ITERATION
+
+1. **Check iteration count**:
+   - If iteration > 3 for same phase: WARN — consider fundamental approach change
+   - If iteration > 5: STRONG WARNING — escalate to product-level re-planning
+
+2. **Check for oscillation**:
+   - If metrics alternate between improving and regressing: detect oscillation pattern
+   - Suggest: lock hyperparameters, change evaluation methodology, or accept
+
+3. **Display guard status**:
+   ```
+   Iteration #{N} of max 5 for this phase.
+   {Guard status message if applicable}
+   ```
+
+---
+
+## Step 8: ROUTE NEXT ACTION
+
+| Option Taken | Next Step |
+|-------------|-----------|
+| Survey alternatives (with new method) | `/grd:plan-phase {N}` — re-plan with new approach |
+| Adjust approach | `/grd:execute-phase {N}` — re-execute modified plan |
+| Adjust targets | `/grd:eval-report {N}` — re-evaluate with new targets |
+| Skip | `/grd:verify-phase {N}` or next phase |
+| Max iterations reached | `/grd:product-plan` — re-evaluate product strategy |
+
+</process>
+
+<output>
+**FILES_UPDATED:**
+- `${phase_dir}/EVAL.md` — history section updated
+- `${phase_dir}/PLAN.md` — updated if approach adjusted
+- `.planning/KNOWHOW.md` — failure analysis and learnings appended
+- `.planning/ROADMAP.md` — updated if targets/status changed
+
+**DISPLAY**: Failure analysis, option selection, and next-step routing
+
+**GIT**: Committed: `iterate: phase {N} iter #{iteration} — {option_chosen}`
+</output>
+
+<error_handling>
+- **EVAL.md has no results**: STOP, direct to `/grd:eval-report` first
+- **No below-target metrics**: Nothing to iterate on — inform user, suggest verify-phase
+- **KNOWHOW.md missing**: Create it with first iteration entry
+- **Iteration history malformed**: Reconstruct from EVAL.md results timestamps
+- **All options seem equally bad**: Recommend escalating to `/grd:product-plan` for strategy review
+</error_handling>
+
+<success_criteria>
+- Failure analysis identifies specific root cause (not generic "needs improvement")
+- Option recommendation is justified with evidence
+- KNOWHOW.md captures reusable learning
+- Iteration is recorded in EVAL.md history
+- Infinite iteration guard is enforced
+- Next action is clear and specific
+</success_criteria>

package/commands/list-phase-assumptions.md

@@ -0,0 +1,217 @@
+---
+description: Surface Claude's assumptions about a phase before planning
+argument-hint: <phase number>
+---
+
+<purpose>
+Surface Claude's assumptions about a phase before planning, enabling users to correct misconceptions early.
+
+Key difference from discuss-phase: This is ANALYSIS of what Claude thinks, not INTAKE of what user knows. No file output - purely conversational to prompt discussion.
+</purpose>
+
+<process>
+
+<step name="validate_phase" priority="first">
+Phase number: $ARGUMENTS (required)
+
+**If argument missing:**
+
+```
+Error: Phase number required.
+
+Usage: /grd:list-phase-assumptions [phase-number]
+Example: /grd:list-phase-assumptions 3
+```
+
+Exit workflow.
+
+**If argument provided:**
+Validate phase exists in roadmap:
+
+```bash
+cat .planning/ROADMAP.md | grep -i "Phase ${PHASE}"
+```
+
+**If phase not found:**
+
+```
+Error: Phase ${PHASE} not found in roadmap.
+
+Available phases:
+[list phases from roadmap]
+```
+
+Exit workflow.
+
+**If phase found:**
+Parse phase details from roadmap:
+
+- Phase number
+- Phase name
+- Phase description/goal
+- Any scope details mentioned
+
+Continue to analyze_phase.
+</step>
+
+<step name="analyze_phase">
+**First, check if CONTEXT.md exists for this phase:**
+```bash
+cat ${PHASE_DIR}/*-CONTEXT.md 2>/dev/null
+```
+If CONTEXT.md exists, incorporate its locked decisions, discretion areas, and deferred ideas into your assumption analysis. Note which assumptions align with or contradict the existing context.
+
+Based on roadmap description and project context, identify assumptions across seven areas:
+
+**1. Technical Approach:**
+What libraries, frameworks, patterns, or tools would Claude use?
+- "I'd use X library because..."
+- "I'd follow Y pattern because..."
+- "I'd structure this as Z because..."
+
+**2. Implementation Order:**
+What would Claude build first, second, third?
+- "I'd start with X because it's foundational"
+- "Then Y because it depends on X"
+- "Finally Z because..."
+
+**3. Scope Boundaries:**
+What's included vs excluded in Claude's interpretation?
+- "This phase includes: A, B, C"
+- "This phase does NOT include: D, E, F"
+- "Boundary ambiguities: G could go either way"
+
+**4. Risk Areas:**
+Where does Claude expect complexity or challenges?
+- "The tricky part is X because..."
+- "Potential issues: Y, Z"
+- "I'd watch out for..."
+
+**5. Dependencies:**
+What does Claude assume exists or needs to be in place?
+- "This assumes X from previous phases"
+- "External dependencies: Y, Z"
+- "This will be consumed by..."
+
+**6. Research Methodology:**
+What papers, methods, or prior work inform this phase?
+- "I'd base this on paper X because..."
+- "The approach from LANDSCAPE.md recommends Y"
+- "KNOWHOW.md notes Z about this technique"
+- "I'd follow the method from deep-dive: [paper-slug]"
+- "Alternative approaches considered: A, B (rejected because...)"
+
+**7. Evaluation Strategy:**
+How would Claude verify this phase meets quantitative targets?
+- "Tier 1 sanity: model loads, output shape correct, no NaN"
+- "Tier 2 proxy: run on Set5, expect PSNR > X"
+- "Tier 3 deferred: full eval on all datasets at milestone boundary"
+- "Baseline comparison: must not regress from BASELINE.md values"
+- "Key metrics: [list from BENCHMARKS.md or eval_config]"
+
+Be honest about uncertainty. Mark assumptions with confidence levels:
+- "Fairly confident: ..." (clear from roadmap)
+- "Assuming: ..." (reasonable inference)
+- "Unclear: ..." (could go multiple ways)
+</step>
+
+<step name="present_assumptions">
+Present assumptions in a clear, scannable format:
+
+```
+## My Assumptions for Phase ${PHASE}: ${PHASE_NAME}
+
+### Technical Approach
+[List assumptions about how to implement]
+
+### Implementation Order
+[List assumptions about sequencing]
+
+### Scope Boundaries
+**In scope:** [what's included]
+**Out of scope:** [what's excluded]
+**Ambiguous:** [what could go either way]
+
+### Risk Areas
+[List anticipated challenges]
+
+### Dependencies
+**From prior phases:** [what's needed]
+**External:** [third-party needs]
+**Feeds into:** [what future phases need from this]
+
+### Research Methodology
+**Papers/methods:** [what informs the approach]
+**LANDSCAPE.md alignment:** [does chosen method match survey recommendations?]
+**KNOWHOW.md considerations:** [relevant lessons from prior iterations]
+
+### Evaluation Strategy
+**Verification tier:** [Tier 1 sanity / Tier 2 proxy / Tier 3 full]
+**Key metrics:** [what to measure]
+**Baseline:** [what values to compare against]
+**Deferred validations:** [what cannot be verified now]
+
+---
+
+**What do you think?**
+
+Are these assumptions accurate? Let me know:
+- What I got right
+- What I got wrong
+- What I'm missing
+```
+
+Wait for user response.
+</step>
+
+<step name="gather_feedback">
+**If user provides corrections:**
+
+Acknowledge the corrections:
+
+```
+Key corrections:
+- [correction 1]
+- [correction 2]
+
+This changes my understanding significantly. [Summarize new understanding]
+```
+
+**If user confirms assumptions:**
+
+```
+Assumptions validated.
+```
+
+Continue to offer_next.
+</step>
+
+<step name="offer_next">
+Present next steps:
+
+```
+What's next?
+1. Discuss context (/grd:discuss-phase ${PHASE}) - Let me ask you questions to build comprehensive context
+2. Plan this phase (/grd:plan-phase ${PHASE}) - Create detailed execution plans
+3. Research context (/grd:research-phase ${PHASE}) - Survey literature and build research context first
+4. Re-examine assumptions - I'll analyze again with your corrections
+5. Done for now
+```
+
+Wait for user selection.
+
+If "Discuss context": Note that CONTEXT.md will incorporate any corrections discussed here
+If "Plan this phase": Proceed knowing assumptions are understood
+If "Re-examine": Return to analyze_phase with updated understanding
+</step>
+
+</process>
+
+<success_criteria>
+- Phase number validated against roadmap
+- Assumptions surfaced across seven areas: technical approach, implementation order, scope, risks, dependencies, research methodology, evaluation strategy
+- Confidence levels marked where appropriate
+- "What do you think?" prompt presented
+- User feedback acknowledged
+- Clear next steps offered
+</success_criteria>