get-research-done 1.1.0

package/get-research-done/templates/context.md

@@ -0,0 +1,283 @@
+# Phase Context Template
+
+Template for `.planning/phases/XX-name/{phase}-CONTEXT.md` - captures implementation decisions for a phase.
+
+**Purpose:** Document decisions that downstream agents need. Researcher uses this to know WHAT to investigate. Planner uses this to know WHAT choices are locked vs flexible.
+
+**Key principle:** Categories are NOT predefined. They emerge from what was actually discussed for THIS phase. A CLI phase has CLI-relevant sections, a UI phase has UI-relevant sections.
+
+**Downstream consumers:**
+- `grd-phase-researcher` — Reads decisions to focus research (e.g., "card layout" → research card component patterns)
+- `grd-planner` — Reads decisions to create specific tasks (e.g., "infinite scroll" → task includes virtualization)
+
+---
+
+## File Template
+
+```markdown
+# Phase [X]: [Name] - Context
+
+**Gathered:** [date]
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+[Clear statement of what this phase delivers — the scope anchor. This comes from ROADMAP.md and is fixed. Discussion clarifies implementation within this boundary.]
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### [Area 1 that was discussed]
+- [Specific decision made]
+- [Another decision if applicable]
+
+### [Area 2 that was discussed]
+- [Specific decision made]
+
+### [Area 3 that was discussed]
+- [Specific decision made]
+
+### Claude's Discretion
+[Areas where user explicitly said "you decide" — Claude has flexibility here during planning/implementation]
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+[Any particular references, examples, or "I want it like X" moments from discussion. Product references, specific behaviors, interaction patterns.]
+
+[If none: "No specific requirements — open to standard approaches"]
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+[Ideas that came up during discussion but belong in other phases. Captured here so they're not lost, but explicitly out of scope for this phase.]
+
+[If none: "None — discussion stayed within phase scope"]
+
+</deferred>
+
+---
+
+*Phase: XX-name*
+*Context gathered: [date]*
+```
+
+<good_examples>
+
+**Example 1: Visual feature (Post Feed)**
+
+```markdown
+# Phase 3: Post Feed - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Display posts from followed users in a scrollable feed. Users can view posts and see engagement counts. Creating posts and interactions are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Layout style
+- Card-based layout, not timeline or list
+- Each card shows: author avatar, name, timestamp, full post content, reaction counts
+- Cards have subtle shadows, rounded corners — modern feel
+
+### Loading behavior
+- Infinite scroll, not pagination
+- Pull-to-refresh on mobile
+- New posts indicator at top ("3 new posts") rather than auto-inserting
+
+### Empty state
+- Friendly illustration + "Follow people to see posts here"
+- Suggest 3-5 accounts to follow based on interests
+
+### Claude's Discretion
+- Loading skeleton design
+- Exact spacing and typography
+- Error state handling
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I like how Twitter shows the new posts indicator without disrupting your scroll position"
+- Cards should feel like Linear's issue cards — clean, not cluttered
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Commenting on posts — Phase 5
+- Bookmarking posts — add to backlog
+
+</deferred>
+
+---
+
+*Phase: 03-post-feed*
+*Context gathered: 2025-01-20*
+```
+
+**Example 2: CLI tool (Database backup)**
+
+```markdown
+# Phase 2: Backup Command - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+CLI command to backup database to local file or S3. Supports full and incremental backups. Restore command is a separate phase.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Output format
+- JSON for programmatic use, table format for humans
+- Default to table, --json flag for JSON
+- Verbose mode (-v) shows progress, silent by default
+
+### Flag design
+- Short flags for common options: -o (output), -v (verbose), -f (force)
+- Long flags for clarity: --incremental, --compress, --encrypt
+- Required: database connection string (positional or --db)
+
+### Error recovery
+- Retry 3 times on network failure, then fail with clear message
+- --no-retry flag to fail fast
+- Partial backups are deleted on failure (no corrupt files)
+
+### Claude's Discretion
+- Exact progress bar implementation
+- Compression algorithm choice
+- Temp file handling
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I want it to feel like pg_dump — familiar to database people"
+- Should work in CI pipelines (exit codes, no interactive prompts)
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Scheduled backups — separate phase
+- Backup rotation/retention — add to backlog
+
+</deferred>
+
+---
+
+*Phase: 02-backup-command*
+*Context gathered: 2025-01-20*
+```
+
+**Example 3: Organization task (Photo library)**
+
+```markdown
+# Phase 1: Photo Organization - Context
+
+**Gathered:** 2025-01-20
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Organize existing photo library into structured folders. Handle duplicates and apply consistent naming. Tagging and search are separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Grouping criteria
+- Primary grouping by year, then by month
+- Events detected by time clustering (photos within 2 hours = same event)
+- Event folders named by date + location if available
+
+### Duplicate handling
+- Keep highest resolution version
+- Move duplicates to _duplicates folder (don't delete)
+- Log all duplicate decisions for review
+
+### Naming convention
+- Format: YYYY-MM-DD_HH-MM-SS_originalname.ext
+- Preserve original filename as suffix for searchability
+- Handle name collisions with incrementing suffix
+
+### Claude's Discretion
+- Exact clustering algorithm
+- How to handle photos with no EXIF data
+- Folder emoji usage
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- "I want to be able to find photos by roughly when they were taken"
+- Don't delete anything — worst case, move to a review folder
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Face detection grouping — future phase
+- Cloud sync — out of scope for now
+
+</deferred>
+
+---
+
+*Phase: 01-photo-organization*
+*Context gathered: 2025-01-20*
+```
+
+</good_examples>
+
+<guidelines>
+**This template captures DECISIONS for downstream agents.**
+
+The output should answer: "What does the researcher need to investigate? What choices are locked for the planner?"
+
+**Good content (concrete decisions):**
+- "Card-based layout, not timeline"
+- "Retry 3 times on network failure, then fail"
+- "Group by year, then by month"
+- "JSON for programmatic use, table for humans"
+
+**Bad content (too vague):**
+- "Should feel modern and clean"
+- "Good user experience"
+- "Fast and responsive"
+- "Easy to use"
+
+**After creation:**
+- File lives in phase directory: `.planning/phases/XX-name/{phase}-CONTEXT.md`
+- `grd-phase-researcher` uses decisions to focus investigation
+- `grd-planner` uses decisions + research to create executable tasks
+- Downstream agents should NOT need to ask the user again about captured decisions
+</guidelines>

package/get-research-done/templates/continue-here.md

@@ -0,0 +1,78 @@
+# Continue-Here Template
+
+Copy and fill this structure for `.planning/phases/XX-name/.continue-here.md`:
+
+```yaml
+---
+phase: XX-name
+task: 3
+total_tasks: 7
+status: in_progress
+last_updated: 2025-01-15T14:30:00Z
+---
+```
+
+```markdown
+<current_state>
+[Where exactly are we? What's the immediate context?]
+</current_state>
+
+<completed_work>
+[What got done this session - be specific]
+
+- Task 1: [name] - Done
+- Task 2: [name] - Done
+- Task 3: [name] - In progress, [what's done on it]
+</completed_work>
+
+<remaining_work>
+[What's left in this phase]
+
+- Task 3: [name] - [what's left to do]
+- Task 4: [name] - Not started
+- Task 5: [name] - Not started
+</remaining_work>
+
+<decisions_made>
+[Key decisions and why - so next session doesn't re-debate]
+
+- Decided to use [X] because [reason]
+- Chose [approach] over [alternative] because [reason]
+</decisions_made>
+
+<blockers>
+[Anything stuck or waiting on external factors]
+
+- [Blocker 1]: [status/workaround]
+</blockers>
+
+<context>
+[Mental state, "vibe", anything that helps resume smoothly]
+
+[What were you thinking about? What was the plan?
+This is the "pick up exactly where you left off" context.]
+</context>
+
+<next_action>
+[The very first thing to do when resuming]
+
+Start with: [specific action]
+</next_action>
+```
+
+<yaml_fields>
+Required YAML frontmatter:
+
+- `phase`: Directory name (e.g., `02-authentication`)
+- `task`: Current task number
+- `total_tasks`: How many tasks in phase
+- `status`: `in_progress`, `blocked`, `almost_done`
+- `last_updated`: ISO timestamp
+</yaml_fields>
+
+<guidelines>
+- Be specific enough that a fresh Claude instance understands immediately
+- Include WHY decisions were made, not just what
+- The `<next_action>` should be actionable without reading anything else
+- This file gets DELETED after resume - it's not permanent storage
+</guidelines>

package/get-research-done/templates/critic-log.md

@@ -0,0 +1,288 @@
+# Critic Evaluation: {{run_name}}
+
+**Timestamp:** {{timestamp}}
+**Iteration:** {{iteration_number}}
+**Objective:** {{brief_hypothesis}}
+
+---
+
+## Verdict
+
+**Decision:** {{PROCEED | REVISE_METHOD | REVISE_DATA | ESCALATE}}
+**Confidence:** {{HIGH | MEDIUM | LOW}}
+
+## Reasoning
+
+{{explanation_of_routing_decision}}
+
+{{context_for_why_this_verdict_makes_sense}}
+
+{{evidence_supporting_decision}}
+
+## Metrics Summary
+
+| Metric | Value | Threshold | Comparison | Result |
+|--------|-------|-----------|------------|--------|
+| {{metric_name}} | {{value}} | {{threshold}} | {{>|<|=}} | {{PASS|FAIL}} |
+
+**Composite Score:** {{weighted_average}} (threshold: {{composite_threshold}})
+
+**Baseline Comparison:** {{if_baseline_defined}}
+
+| Metric | Baseline | Actual | Improvement | % Change |
+|--------|----------|--------|-------------|----------|
+| {{metric_name}} | {{baseline_value}} | {{actual_value}} | {{delta}} | {{percentage}} |
+
+## Strengths
+
+{{list_of_what_experiment_does_well}}
+
+Examples:
+- Implementation correctly uses stratified k-fold as specified in OBJECTIVE.md
+- Random seed set to 42 for reproducibility
+- Clear documentation in README.md
+- Hyperparameters well-documented in config.yaml
+- Code quality is high with proper error handling
+- Training/validation curves show healthy learning behavior
+
+## Weaknesses
+
+{{list_of_issues_or_concerns}}
+
+Examples:
+- F1 score (0.78) below threshold (0.80)
+- Train-test gap of 0.08 suggests mild overfitting
+- Learning rate may be too high (training loss plateaus early)
+- Missing validation curves in output
+- Evaluation methodology doesn't match OBJECTIVE.md (used holdout instead of k-fold)
+- Random seed not set (non-reproducible results)
+
+## Recommendations
+
+{{list_of_specific_actionable_suggestions}}
+
+**For REVISE_METHOD verdicts:**
+- Reduce learning rate from 0.1 to 0.01
+- Add dropout layer with rate 0.3 to reduce overfitting
+- Increase training epochs from 50 to 100 (training curve not plateaued)
+- Add early stopping with patience=10 to prevent overfitting
+- Fix data split bug on line 45 in train.py
+- Add missing metrics to output (currently missing F1 score)
+
+**For REVISE_DATA verdicts:**
+- Investigate feature 'transaction_id' for potential leakage (dominates feature importance)
+- Re-analyze temporal features for leakage (results suggest future information used)
+- Verify target column is correct (baseline outperforms model significantly)
+- Check for train-test overlap (metrics suggest data contamination)
+- Investigate data quality issues (high variance across folds)
+
+**For PROCEED verdicts:**
+- Document validation approach in final report
+- Consider additional robustness checks before production
+- Monitor for drift in production deployment
+
+**For ESCALATE verdicts:**
+- Human decision required (see evidence package below)
+- Consider revising hypothesis or success criteria
+- May need to collect additional data
+- Strategic pivot may be necessary
+
+## Investigation Notes
+
+{{notes_from_scientific_skepticism_checks}}
+
+### Suspicious Success Check
+
+{{result_of_investigation_for_unusually_high_metrics}}
+
+- Metrics: {{list_metrics_and_values}}
+- Task complexity: {{assessment_of_difficulty}}
+- Assessment: {{plausible | suspicious | highly_suspicious}}
+- Reasoning: {{why}}
+
+### Train-Test Gap
+
+- Train metric: {{value}}
+- Validation metric: {{value}}
+- Gap: {{delta}}
+- Assessment: {{acceptable | moderate_concern | high_concern}}
+- Reasoning: {{why}}
+
+### Reproducibility
+
+- Random seed set: {{yes|no}}
+- Dependencies documented: {{yes|no}}
+- Data references recorded: {{yes|no}}
+- Assessment: {{reproducible | partially_reproducible | non_reproducible}}
+
+### Data Integrity
+
+{{if_DATA_REPORT_referenced}}
+
+- Leakage features excluded: {{yes|no|N/A}}
+- Class imbalance handled: {{yes|no|N/A}}
+- Temporal splits used if needed: {{yes|no|N/A}}
+- Assessment: {{concerns_none | concerns_minor | concerns_major}}
+
+### Code Quality
+
+- Evaluation matches OBJECTIVE.md: {{yes|no}}
+- Data split correct: {{yes|no}}
+- Hyperparameters documented: {{yes|no}}
+- Error handling present: {{yes|no}}
+- Assessment: {{good | acceptable | needs_improvement}}
+
+## Trend Analysis
+
+**Iteration Trend:** {{improving | stagnant | degrading | first_run}}
+
+{{comparison_with_previous_iterations_if_available}}
+
+**Historical Performance:**
+
+| Iteration | Composite Score | Key Changes | Verdict |
+|-----------|----------------|-------------|---------|
+| 1 | {{value}} | {{change_description}} | {{verdict}} |
+| 2 | {{value}} | {{change_description}} | {{verdict}} |
+| 3 (current) | {{value}} | {{change_description}} | {{verdict}} |
+
+**Trend Assessment:**
+
+{{detailed_analysis_of_progress_across_iterations}}
+
+Examples:
+- "Metrics improving steadily (+0.02 per iteration). Current trajectory suggests threshold will be reached in 1-2 more iterations."
+- "Metrics stagnant across 3 iterations despite different hyperparameters. May indicate fundamental limitation."
+- "Metrics degrading. Recent changes counterproductive—consider reverting to iteration 1 approach."
+
+**Cycle Detection:**
+
+{{if_same_verdict_repeated}}
+
+- Same verdict: {{verdict}} repeated {{N}} times
+- Assessment: {{no_cycle | potential_cycle | cycle_detected}}
+- Action: {{continue | escalate | try_different_approach}}
+
+## Next Steps
+
+{{based_on_verdict}}
+
+### If PROCEED (HIGH confidence)
+Ready for quantitative evaluation by Evaluator agent.
+
+**Action:** Run `/grd:evaluate` to generate SCORECARD.json
+
+**What happens next:**
+- Evaluator will run comprehensive benchmark suite
+- Results will be compared against OBJECTIVE.md criteria
+- SCORECARD.json will be generated for human evaluation gate
+
+### If PROCEED (MEDIUM confidence)
+Metrics meet criteria but minor concerns noted.
+
+**Action:** Proceed to Evaluator with caveats
+
+**Caveats:**
+{{list_of_minor_concerns_to_monitor}}
+
+### If PROCEED (LOW confidence)
+**HUMAN GATE REQUIRED**
+
+Metrics pass thresholds but concerns exist:
+{{list_of_concerns}}
+
+**Question for human:**
+Should we proceed to Evaluator despite concerns, or investigate further?
+
+**Options:**
+1. Proceed to Evaluator (accept concerns)
+2. REVISE_METHOD (address concerns first)
+3. ESCALATE (need strategic decision)
+
+### If REVISE_METHOD
+Address implementation issues and re-run experiment.
+
+**Action:** Implement recommendations above, then run experiment again
+
+**Specific fixes needed:**
+{{prioritized_list_of_fixes}}
+
+**Expected impact:**
+{{what_should_improve_if_fixes_applied}}
+
+**Estimated effort:** {{low|medium|high}}
+
+### If REVISE_DATA
+Return to data exploration with specific concerns.
+
+**Action:** Run `/grd:explore` with focus areas
+
+**Concerns to investigate:**
+{{list_of_specific_data_concerns}}
+
+**What to look for:**
+{{guidance_for_data_re_analysis}}
+
+**Updates needed:**
+- Append findings to DATA_REPORT.md
+- Update OBJECTIVE.md if constraints change
+- Re-run experiment with corrected data
+
+### If ESCALATE
+Human decision required—cannot determine clear path forward.
+
+**Reason for escalation:** {{cycle_detected | ambiguous_root_cause | iteration_limit | strategic_decision_needed}}
+
+**Evidence Package:**
+
+#### Iteration History
+{{summary_of_all_attempts}}
+
+#### Conflicting Signals
+{{description_of_ambiguity_or_contradiction}}
+
+#### Attempted Resolutions
+{{what_was_tried_and_why_it_didnt_work}}
+
+#### Recommendation
+{{suggested_strategic_direction_or_questions_for_human}}
+
+**Human Options:**
+1. Continue with more iterations (increase limit)
+2. Revise hypothesis or success criteria (update OBJECTIVE.md)
+3. Archive hypothesis as disproven (document learnings)
+4. Return to data collection (need more/better data)
+5. Strategic pivot (fundamentally different approach)
+
+## Appendix
+
+### Falsification Criteria Status
+
+{{if_falsification_criteria_defined_in_OBJECTIVE}}
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| {{criterion_name}} | {{not_met | approaching | met}} | {{details}} |
+
+**Assessment:** {{hypothesis_still_viable | approaching_falsification | falsified}}
+
+### Experiment Metadata
+
+- **Run directory:** {{path_to_run_NNN}}
+- **Code files:** {{list_of_key_files}}
+- **Configuration:** {{path_to_config_yaml_or_none}}
+- **Documentation:** {{path_to_README_or_none}}
+- **Training time:** {{duration_in_seconds_or_minutes}}
+- **Compute resources:** {{cpu|gpu|tpu}} - {{details}}
+
+### References
+
+- **OBJECTIVE.md:** `.planning/OBJECTIVE.md`
+- **DATA_REPORT.md:** {{path_or_none}}
+- **Previous iterations:** {{paths_to_previous_CRITIC_LOGs}}
+
+---
+
+*Critique by grd-critic*
+*Agent version: GRD Critic v1.0*
+*Referenced: .planning/OBJECTIVE.md*