get-research-done 1.1.0

package/commands/grd/add-phase.md

@@ -0,0 +1,207 @@
+---
+name: grd:add-phase
+description: Add phase to end of current milestone in roadmap
+argument-hint: <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Add a new integer phase to the end of the current milestone in the roadmap.
+
+This command appends sequential phases to the current milestone's phase list, automatically calculating the next phase number based on existing phases.
+
+Purpose: Add planned work discovered during execution that belongs at the end of current milestone.
+</objective>
+
+<execution_context>
+@.planning/ROADMAP.md
+@.planning/STATE.md
+</execution_context>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- All arguments become the phase description
+- Example: `/grd:add-phase Add authentication` → description = "Add authentication"
+- Example: `/grd:add-phase Fix critical performance issues` → description = "Fix critical performance issues"
+
+If no arguments provided:
+
+```
+ERROR: Phase description required
+Usage: /grd:add-phase <description>
+Example: /grd:add-phase Add authentication system
+```
+
+Exit.
+</step>
+
+<step name="load_roadmap">
+Load the roadmap file:
+
+```bash
+if [ -f .planning/ROADMAP.md ]; then
+  ROADMAP=".planning/ROADMAP.md"
+else
+  echo "ERROR: No roadmap found (.planning/ROADMAP.md)"
+  exit 1
+fi
+```
+
+Read roadmap content for parsing.
+</step>
+
+<step name="find_current_milestone">
+Parse the roadmap to find the current milestone section:
+
+1. Locate the "## Current Milestone:" heading
+2. Extract milestone name and version
+3. Identify all phases under this milestone (before next "---" separator or next milestone heading)
+4. Parse existing phase numbers (including decimals if present)
+
+Example structure:
+
+```
+## Current Milestone: v1.0 Foundation
+
+### Phase 4: Focused Command System
+### Phase 5: Path Routing & Validation
+### Phase 6: Documentation & Distribution
+```
+
+</step>
+
+<step name="calculate_next_phase">
+Find the highest integer phase number in the current milestone:
+
+1. Extract all phase numbers from phase headings (### Phase N:)
+2. Filter to integer phases only (ignore decimals like 4.1, 4.2)
+3. Find the maximum integer value
+4. Add 1 to get the next phase number
+
+Example: If phases are 4, 5, 5.1, 6 → next is 7
+
+Format as two-digit: `printf "%02d" $next_phase`
+</step>
+
+<step name="generate_slug">
+Convert the phase description to a kebab-case slug:
+
+```bash
+# Example transformation:
+# "Add authentication" → "add-authentication"
+# "Fix critical performance issues" → "fix-critical-performance-issues"
+
+slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+```
+
+Phase directory name: `{two-digit-phase}-{slug}`
+Example: `07-add-authentication`
+</step>
+
+<step name="create_phase_directory">
+Create the phase directory structure:
+
+```bash
+phase_dir=".planning/phases/${phase_num}-${slug}"
+mkdir -p "$phase_dir"
+```
+
+Confirm: "Created directory: $phase_dir"
+</step>
+
+<step name="update_roadmap">
+Add the new phase entry to the roadmap:
+
+1. Find the insertion point (after last phase in current milestone, before "---" separator)
+2. Insert new phase heading:
+
+   ```
+   ### Phase {N}: {Description}
+
+   **Goal:** [To be planned]
+   **Depends on:** Phase {N-1}
+   **Plans:** 0 plans
+
+   Plans:
+   - [ ] TBD (run /grd:plan-phase {N} to break down)
+
+   **Details:**
+   [To be added during planning]
+   ```
+
+3. Write updated roadmap back to file
+
+Preserve all other content exactly (formatting, spacing, other phases).
+</step>
+
+<step name="update_project_state">
+Update STATE.md to reflect the new phase:
+
+1. Read `.planning/STATE.md`
+2. Under "## Current Position" → "**Next Phase:**" add reference to new phase
+3. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
+   ```
+   - Phase {N} added: {description}
+   ```
+
+If "Roadmap Evolution" section doesn't exist, create it.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {N} added to current milestone:
+- Description: {description}
+- Directory: .planning/phases/{phase-num}-{slug}/
+- Status: Not planned yet
+
+Roadmap updated: {roadmap-path}
+Project state updated: .planning/STATE.md
+
+---
+
+## ▶ Next Up
+
+**Phase {N}: {description}**
+
+`/grd:plan-phase {N}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/grd:add-phase <description>` — add another phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<anti_patterns>
+
+- Don't modify phases outside current milestone
+- Don't renumber existing phases
+- Don't use decimal numbering (that's /grd:insert-phase)
+- Don't create plans yet (that's /grd:plan-phase)
+- Don't commit changes (user decides when to commit)
+  </anti_patterns>
+
+<success_criteria>
+Phase addition is complete when:
+
+- [ ] Phase directory created: `.planning/phases/{NN}-{slug}/`
+- [ ] Roadmap updated with new phase entry
+- [ ] STATE.md updated with roadmap evolution note
+- [ ] New phase appears at end of current milestone
+- [ ] Next phase number calculated correctly (ignoring decimals)
+- [ ] User informed of next steps
+      </success_criteria>

package/commands/grd/add-todo.md

@@ -0,0 +1,193 @@
+---
+name: grd:add-todo
+description: Capture idea or task as todo from current conversation context
+argument-hint: [optional description]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+---
+
+<objective>
+Capture an idea, task, or issue that surfaces during a GSD session as a structured todo for later work.
+
+Enables "thought → capture → continue" flow without losing context or derailing current work.
+</objective>
+
+<context>
+@.planning/STATE.md
+</context>
+
+<process>
+
+<step name="ensure_directory">
+```bash
+mkdir -p .planning/todos/pending .planning/todos/done
+```
+</step>
+
+<step name="check_existing_areas">
+```bash
+ls .planning/todos/pending/*.md 2>/dev/null | xargs -I {} grep "^area:" {} 2>/dev/null | cut -d' ' -f2 | sort -u
+```
+
+Note existing areas for consistency in infer_area step.
+</step>
+
+<step name="extract_content">
+**With arguments:** Use as the title/focus.
+- `/grd:add-todo Add auth token refresh` → title = "Add auth token refresh"
+
+**Without arguments:** Analyze recent conversation to extract:
+- The specific problem, idea, or task discussed
+- Relevant file paths mentioned
+- Technical details (error messages, line numbers, constraints)
+
+Formulate:
+- `title`: 3-10 word descriptive title (action verb preferred)
+- `problem`: What's wrong or why this is needed
+- `solution`: Approach hints or "TBD" if just an idea
+- `files`: Relevant paths with line numbers from conversation
+</step>
+
+<step name="infer_area">
+Infer area from file paths:
+
+| Path pattern | Area |
+|--------------|------|
+| `src/api/*`, `api/*` | `api` |
+| `src/components/*`, `src/ui/*` | `ui` |
+| `src/auth/*`, `auth/*` | `auth` |
+| `src/db/*`, `database/*` | `database` |
+| `tests/*`, `__tests__/*` | `testing` |
+| `docs/*` | `docs` |
+| `.planning/*` | `planning` |
+| `scripts/*`, `bin/*` | `tooling` |
+| No files or unclear | `general` |
+
+Use existing area from step 2 if similar match exists.
+</step>
+
+<step name="check_duplicates">
+```bash
+grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null
+```
+
+If potential duplicate found:
+1. Read the existing todo
+2. Compare scope
+
+If overlapping, use AskUserQuestion:
+- header: "Duplicate?"
+- question: "Similar todo exists: [title]. What would you like to do?"
+- options:
+  - "Skip" — keep existing todo
+  - "Replace" — update existing with new context
+  - "Add anyway" — create as separate todo
+</step>
+
+<step name="create_file">
+```bash
+timestamp=$(date "+%Y-%m-%dT%H:%M")
+date_prefix=$(date "+%Y-%m-%d")
+```
+
+Generate slug from title (lowercase, hyphens, no special chars).
+
+Write to `.planning/todos/pending/${date_prefix}-${slug}.md`:
+
+```markdown
+---
+created: [timestamp]
+title: [title]
+area: [area]
+files:
+  - [file:lines]
+---
+
+## Problem
+
+[problem description - enough context for future Claude to understand weeks later]
+
+## Solution
+
+[approach hints or "TBD"]
+```
+</step>
+
+<step name="update_state">
+If `.planning/STATE.md` exists:
+
+1. Count todos: `ls .planning/todos/pending/*.md 2>/dev/null | wc -l`
+2. Update "### Pending Todos" under "## Accumulated Context"
+</step>
+
+<step name="git_commit">
+Commit the todo and any updated state:
+
+**Check planning config:**
+
+```bash
+COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
+```
+
+**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations, log "Todo saved (not committed - commit_docs: false)"
+
+**If `COMMIT_PLANNING_DOCS=true` (default):**
+
+```bash
+git add .planning/todos/pending/[filename]
+[ -f .planning/STATE.md ] && git add .planning/STATE.md
+git commit -m "$(cat <<'EOF'
+docs: capture todo - [title]
+
+Area: [area]
+EOF
+)"
+```
+
+Confirm: "Committed: docs: capture todo - [title]"
+</step>
+
+<step name="confirm">
+```
+Todo saved: .planning/todos/pending/[filename]
+
+  [title]
+  Area: [area]
+  Files: [count] referenced
+
+---
+
+Would you like to:
+
+1. Continue with current work
+2. Add another todo
+3. View all todos (/grd:check-todos)
+```
+</step>
+
+</process>
+
+<output>
+- `.planning/todos/pending/[date]-[slug].md`
+- Updated `.planning/STATE.md` (if exists)
+</output>
+
+<anti_patterns>
+- Don't create todos for work in current plan (that's deviation rule territory)
+- Don't create elaborate solution sections — captures ideas, not plans
+- Don't block on missing information — "TBD" is fine
+</anti_patterns>
+
+<success_criteria>
+- [ ] Directory structure exists
+- [ ] Todo file created with valid frontmatter
+- [ ] Problem section has enough context for future Claude
+- [ ] No duplicates (checked and resolved)
+- [ ] Area consistent with existing todos
+- [ ] STATE.md updated if exists
+- [ ] Todo and state committed to git
+</success_criteria>

package/commands/grd/architect.md

@@ -0,0 +1,283 @@
+# /grd:architect
+
+**Synthesizes testable hypotheses from data insights with iterative refinement (Phase 3 command)**
+
+---
+name: grd:architect
+description: Synthesize testable hypotheses from data insights with iterative refinement
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+agent: grd-architect
+phase: 3
+requires: [DATA_REPORT.md (optional but recommended)]
+produces: [OBJECTIVE.md]
+---
+
+<objective>
+
+Transform data insights into testable ML hypotheses through an interactive, advisor-like process.
+
+This command enables conversational hypothesis synthesis—the Architect agent proposes hypotheses, explains reasoning, and refines based on user feedback. The agent acts as a research advisor, not a dictator: it suggests directions but accepts user override.
+
+**Creates:**
+- `.planning/OBJECTIVE.md` — testable hypothesis with success metrics, evaluation strategy, baselines, and falsification criteria
+
+**Use cases:**
+- After data exploration: Ground hypothesis in DATA_REPORT.md findings
+- New research direction: Define what to test and how success is measured
+- Experiment planning: Establish clear falsification criteria before implementation
+- Iterative refinement: Collaborate with agent to improve hypothesis quality
+
+**After this command:** Review OBJECTIVE.md for accuracy, then proceed with /grd:research (Phase 4) to implement experiments.
+
+</objective>
+
+<execution_context>
+
+@~/.claude/get-research-done/templates/objective.md
+
+</execution_context>
+
+<process>
+
+## Phase 1: Setup and Context Loading
+
+**Check if project initialized:**
+
+```bash
+[ ! -f .planning/PROJECT.md ] && echo "ERROR: Project not initialized. Run /grd:new-project first." && exit 1
+```
+
+**Check for completed data reconnaissance (soft gate):**
+
+```bash
+ls .planning/DATA_REPORT.md 2>/dev/null
+```
+
+**If DATA_REPORT.md exists:**
+- Note: "Using data insights from DATA_REPORT.md"
+- Read and extract key findings for hypothesis grounding:
+  - Leakage warnings to avoid in hypothesis
+  - Data quality issues that constrain approach
+  - Class balance requiring special handling
+  - Feature correlations suggesting relationships
+- Pass findings to architect agent for context
+
+**If DATA_REPORT.md does NOT exist:**
+- Warn: "WARNING: No DATA_REPORT.md found. Data reconnaissance not completed."
+- Suggest: "Run /grd:explore first to analyze your data before forming hypotheses."
+- Ask: "Continue anyway? (yes/no)"
+- If user says yes: Proceed without data context
+- If user says no: Exit and suggest running /grd:explore
+
+This is a SOFT GATE - warns but allows proceeding. User decides if data-first is needed for their workflow.
+
+**Why this matters:**
+- Hypotheses grounded in data characteristics are more likely to be testable
+- Data quality issues may constrain what's scientifically valid to test
+- Leakage patterns inform which features should be excluded from hypothesis tests
+
+**Load project context:**
+
+```bash
+cat .planning/PROJECT.md
+```
+
+Extract:
+- Project goals and domain context
+- Any stated research questions
+- Domain-specific constraints
+
+## Phase 2: Hypothesis Mode Selection
+
+**Check for optional [direction] argument:**
+
+Parse command invocation for direction text after command name.
+
+**If direction provided:**
+- Use as starting point for hypothesis
+- Mode: "user-directed"
+- Pass direction to architect agent
+
+**If no direction but DATA_REPORT.md exists:**
+- Mode: "auto-propose"
+- Architect will analyze DATA_REPORT.md findings and propose hypothesis
+
+**If neither:**
+- Use AskUserQuestion:
+  ```
+  header: "Hypothesis Direction"
+  question: "What would you like to test? (Or press Enter to auto-propose from DATA_REPORT.md)"
+  options: null  # Free text input
+  ```
+- If user provides text: Mode "user-directed"
+- If empty and DATA_REPORT.md exists: Mode "auto-propose"
+- If empty and no DATA_REPORT.md: Exit with error "No direction provided and no DATA_REPORT.md to auto-propose from"
+
+**Check for flags:**
+
+- `--skip-data-check`: Skip the DATA_REPORT.md soft gate warning
+
+## Phase 3: Spawn Architect Agent
+
+Display banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► SYNTHESIZING HYPOTHESIS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Mode: [auto-propose | user-directed]
+Data context: [DATA_REPORT.md found | No data report]
+```
+
+Spawn grd-architect agent with context:
+
+```
+Task(prompt="
+<mode>
+[auto-propose | user-directed]
+Direction: [user_direction_if_any]
+</mode>
+
+<data_context>
+@.planning/DATA_REPORT.md (if exists)
+
+Key findings to incorporate:
+- Leakage warnings: [list]
+- Data quality issues: [list]
+- Class balance: [summary]
+- Feature correlations: [relevant findings]
+- Missing data patterns: [summary]
+</data_context>
+
+<project_context>
+@.planning/PROJECT.md
+
+Extract:
+- Project goals
+- Domain context
+- Any stated research questions
+</project_context>
+
+<instructions>
+Execute hypothesis synthesis workflow:
+
+1. Propose hypothesis based on mode (auto from data OR user direction)
+2. Explain reasoning and expected outcome
+3. Suggest success metrics and evaluation methodology
+4. Identify baseline options
+5. Define falsification criteria
+6. Await user feedback
+7. Refine if requested, up to 15 iterations
+8. When user approves, generate OBJECTIVE.md
+
+Use template: @get-research-done/templates/objective.md
+Write to: .planning/OBJECTIVE.md
+</instructions>
+", subagent_type="grd-architect", model="sonnet", description="Synthesize testable hypothesis")
+```
+
+## Phase 4: Present Results
+
+After agent completes, read OBJECTIVE.md and present summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GRD ► HYPOTHESIS SYNTHESIZED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Hypothesis: [brief statement from OBJECTIVE.md "What" section]
+
+**Metrics:** [list with weights]
+**Evaluation:** [strategy]
+**Baseline:** [defined | WARNING: not defined]
+**Falsification:** [criteria count] criteria defined
+
+---
+
+**Full objective:** `.planning/OBJECTIVE.md`
+
+**Next steps:**
+- Review OBJECTIVE.md for accuracy
+- Run /grd:research to implement experiment (Phase 4)
+```
+
+**If baseline not defined:**
+Display warning: "⚠️  WARNING: No baseline defined. Cannot claim improvement without comparison. Consider adding baseline to OBJECTIVE.md before proceeding."
+
+**If critical validation issues:**
+Display any warnings from architect agent (e.g., metric weights don't sum to 1.0, no falsification criteria)
+
+</process>
+
+<arguments>
+
+**[direction]** (optional)
+- Text describing what you want to test
+- Examples: "Does feature X improve prediction?", "Can we reduce RMSE below 0.5?"
+- If omitted, Architect will auto-propose from DATA_REPORT.md findings
+
+**Flags:**
+
+`--skip-data-check`
+- Skip the DATA_REPORT.md soft gate warning
+- Use when intentionally working without data reconnaissance
+
+</arguments>
+
+<examples>
+
+**Auto-propose from data:**
+```
+/grd:architect
+# Architect analyzes DATA_REPORT.md and proposes hypothesis
+```
+
+**User-directed hypothesis:**
+```
+/grd:architect "Can ensemble methods improve F1 over single models?"
+# Architect starts from user's direction
+```
+
+**Skip data gate:**
+```
+/grd:architect --skip-data-check
+# Proceed without DATA_REPORT.md warning
+```
+
+**Complex hypothesis:**
+```
+/grd:architect "Test if temporal features reduce false positives by 20% while maintaining recall above 0.85"
+# Architect refines multi-metric hypothesis with user
+```
+
+</examples>
+
+<output>
+
+- `.planning/OBJECTIVE.md` — testable hypothesis with:
+  - Context (problem, motivation, data characteristics, constraints)
+  - Hypothesis (what, why, expected outcome)
+  - Success metrics (weighted, with thresholds)
+  - Evaluation methodology (strategy, parameters, statistical significance)
+  - Baselines (own implementation or literature citations)
+  - Falsification criteria (quantitative preferred)
+  - Constraints and non-goals
+
+</output>
+
+<success_criteria>
+
+- [ ] DATA_REPORT.md soft gate executed (warn if missing)
+- [ ] Mode determined (auto-propose or user-directed)
+- [ ] Architect agent spawned with appropriate context
+- [ ] User can provide direction or receive auto-proposal
+- [ ] OBJECTIVE.md generated with all required sections
+- [ ] Summary presented with next steps
+- [ ] Baseline warning issued if applicable
+
+</success_criteria>