@jokerized/getresearchdone 0.4.1

package/commands/discover.md

@@ -0,0 +1,281 @@
+---
+description: Discover and extract coding standards from existing codebase patterns
+argument-hint: [API | Database | Frontend | Testing | Configuration | custom path]
+---
+
+<purpose>
+Analyze existing codebase files to discover recurring patterns and conventions. Present each discovered pattern interactively so the user can confirm which ones should become enforced standards. Confirmed patterns are written to `.planning/standards/{area}/{pattern-slug}.md` with structured frontmatter and indexed in `.planning/standards/index.yml`.
+</purpose>
+
+<process>
+
+<step name="get_focus_area" priority="first">
+**Get focus area from argument or prompt user.**
+
+If `$ARGUMENTS` contains a focus area, use it. Otherwise, prompt:
+
+```
+AskUserQuestion(
+  header: "Standards Discovery",
+  question: "Which area of the codebase should I analyze for patterns?",
+  options: [
+    { label: "API", description: "Routes, controllers, middleware, request/response patterns" },
+    { label: "Database", description: "Models, queries, migrations, connection patterns" },
+    { label: "Frontend", description: "Components, state management, styling patterns" },
+    { label: "Testing", description: "Test structure, fixtures, assertions, mocking patterns" },
+    { label: "Configuration", description: "Config loading, environment handling, defaults" },
+    { label: "Custom path", description: "Specify a directory or glob pattern to analyze" }
+  ]
+)
+```
+
+Store response as `$AREA`.
+
+If "Custom path" selected, follow up:
+
+```
+AskUserQuestion(
+  header: "Custom Path",
+  question: "Enter the directory path or glob pattern to analyze (e.g., src/services/ or lib/**/*.js):",
+  followUp: null
+)
+```
+
+Store response as `$CUSTOM_PATH`.
+
+Map area to search patterns:
+- **API**: `src/**/routes/**`, `src/**/controllers/**`, `src/**/api/**`, `lib/**/routes/**`, `app/**/controllers/**`
+- **Database**: `src/**/models/**`, `src/**/migrations/**`, `src/**/db/**`, `lib/**/models/**`, `prisma/**`, `drizzle/**`
+- **Frontend**: `src/**/components/**`, `src/**/pages/**`, `src/**/views/**`, `app/**/components/**`
+- **Testing**: `tests/**`, `test/**`, `__tests__/**`, `*.test.*`, `*.spec.*`
+- **Configuration**: `config/**`, `*.config.*`, `.env*`, `src/**/config/**`
+- **Custom path**: Use `$CUSTOM_PATH` directly
+</step>
+
+<step name="find_representative_files">
+**Find 5-10 representative files using Glob.**
+
+Use the search patterns from the previous step to find candidate files. Select 5-10 files that are:
+- Non-trivial (>20 lines)
+- Representative of the area (not generated or vendored)
+- Diverse (different subdirectories or concerns within the area)
+
+If fewer than 5 files found, widen the search. If the mapped globs find nothing, fall back to a broad search of the project and filter by relevance to the area.
+
+Report to user:
+```
+Analyzing {N} files in {area}:
+{list of file paths}
+```
+</step>
+
+<step name="analyze_patterns">
+**Read each file and extract patterns.**
+
+For each file, analyze and note:
+
+1. **Naming conventions** — file names, function names, variable names, class names, export names
+2. **Import/require patterns** — ordering, grouping, aliasing, path conventions
+3. **Error handling** — try/catch structure, error classes, error response format, logging
+4. **Response/return structures** — consistent shapes, status codes, envelope patterns
+5. **Documentation patterns** — JSDoc style, inline comments, header comments, README conventions
+6. **Testing patterns** — describe/it structure, setup/teardown, assertion style, mock patterns
+7. **Code organization** — module structure, export style, separation of concerns
+8. **Configuration patterns** — how defaults are set, env var access, validation
+
+For each pattern category, look for consistency across files. A pattern is significant if it appears in 3+ files or is clearly intentional (e.g., a shared utility enforcing it).
+
+Collect discovered patterns as a list, each with:
+- `name`: Short descriptive name (e.g., "Error response envelope")
+- `category`: One of the categories above
+- `description`: What the pattern is and why it exists
+- `examples`: 2-3 code snippets showing the pattern in use
+- `files`: Which files exhibit this pattern
+- `confidence`: high (5+ files), medium (3-4 files), low (1-2 files but intentional)
+</step>
+
+<step name="present_patterns_interactively">
+**Present each pattern to the user for confirmation.**
+
+For each discovered pattern (sorted by confidence, highest first):
+
+```
+---
+
+## Pattern: {name}
+Category: {category} | Confidence: {confidence} | Found in {N} files
+
+{description}
+
+### Examples
+
+{2-3 code snippets with file attribution}
+
+---
+```
+
+Then ask:
+
+```
+AskUserQuestion(
+  header: "Pattern: {name}",
+  question: "Should this pattern be enforced as a standard?",
+  options: [
+    { label: "Yes — enforce as standard", description: "Add to project standards" },
+    { label: "Yes — with modifications", description: "I want to adjust the description before saving" },
+    { label: "Skip", description: "Not a standard, just coincidence" }
+  ]
+)
+```
+
+If "Yes -- with modifications": ask user for their revised description/rules, then save with their version.
+
+Collect all confirmed patterns as `$CONFIRMED_PATTERNS`.
+</step>
+
+<step name="write_standard_files">
+**Write confirmed standards to `.planning/standards/{area}/`.**
+
+Compute the area slug:
+```bash
+AREA_SLUG=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js generate-slug "$AREA" --raw)
+```
+
+Create the directory:
+```bash
+mkdir -p ${standards_dir}/${AREA_SLUG}
+```
+
+For each confirmed pattern, generate a slug and write a markdown file:
+
+```bash
+PATTERN_SLUG=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js generate-slug "${pattern_name}" --raw)
+```
+
+Write to `.planning/standards/${AREA_SLUG}/${PATTERN_SLUG}.md`:
+
+```markdown
+---
+name: {pattern_name}
+category: {category}
+area: {area}
+confidence: {confidence}
+source_files:
+  - {file1}
+  - {file2}
+discovered: {YYYY-MM-DD}
+status: active
+---
+
+# {pattern_name}
+
+{description}
+
+## Rule
+
+{Concise statement of what the standard requires}
+
+## Examples
+
+### Correct
+
+{code example showing the pattern done right}
+
+### Incorrect
+
+{code example showing what to avoid — inferred from the pattern}
+
+## Rationale
+
+{Why this pattern exists — inferred from codebase context}
+```
+</step>
+
+<step name="update_index">
+**Create or update `.planning/standards/index.yml`.**
+
+If `.planning/standards/index.yml` exists, read it and merge new entries. Otherwise create it.
+
+Format:
+
+```yaml
+# Standards Index — auto-generated by /grd:discover
+# Last updated: {YYYY-MM-DD}
+
+areas:
+  {area_slug}:
+    name: {Area}
+    standards:
+      - slug: {pattern_slug}
+        name: {pattern_name}
+        category: {category}
+        status: active
+        file: {area_slug}/{pattern_slug}.md
+```
+
+Merge new standards into existing areas. Do not remove existing entries.
+</step>
+
+<step name="commit">
+**Commit all standards files.**
+
+```bash
+git add .planning/standards/
+git commit -m "docs(standards): discover {area} patterns — {N} standards extracted"
+```
+
+If nothing to commit (no patterns confirmed), inform user and skip.
+</step>
+
+<step name="completion">
+**Display summary and next steps.**
+
+```
+---
+
+GRD > STANDARDS DISCOVERY COMPLETE
+
+Area: {area}
+Files analyzed: {N}
+Patterns found: {total}
+Standards confirmed: {confirmed_count}
+Standards skipped: {skipped_count}
+
+Written to: .planning/standards/{area_slug}/
+
+Standards:
+{for each confirmed pattern:}
+  - {pattern_name} ({category})
+
+---
+
+Next steps:
+- /grd:discover {other_area} — discover patterns in another area
+- Review standards in .planning/standards/{area_slug}/
+- Standards are automatically loaded during /grd:plan-phase and /grd:execute-phase
+
+---
+```
+</step>
+
+</process>
+
+<error_handling>
+- **No files found for area**: Suggest broader search or ask user for specific paths
+- **No patterns detected**: Report findings, suggest trying a different area or providing more files
+- **generate-slug not available**: Fall back to lowercase-hyphenated manual slug generation
+- **Git commit fails**: Report files written but uncommitted, suggest manual commit
+- **index.yml parse error**: Back up corrupted file, create fresh index
+</error_handling>
+
+<success_criteria>
+- [ ] User selects or provides a focus area
+- [ ] 5-10 representative files found and analyzed
+- [ ] Patterns extracted across multiple categories (naming, imports, errors, etc.)
+- [ ] Each pattern presented interactively with examples
+- [ ] User confirms/skips each pattern
+- [ ] Confirmed patterns written to `.planning/standards/{area}/{slug}.md` with frontmatter
+- [ ] `.planning/standards/index.yml` created or updated
+- [ ] All standards files committed to git
+- [ ] Summary displayed with counts and next steps
+</success_criteria>

package/commands/discuss-phase.md

@@ -0,0 +1,188 @@
+---
+description: Extract implementation decisions before phase planning
+argument-hint: <phase number>
+---
+
+<purpose>
+Extract implementation decisions that downstream agents need. Analyze the phase to identify gray areas, let the user choose what to discuss, then deep-dive each selected area until satisfied.
+
+You are a thinking partner, not an interviewer. The user is the visionary — you are the builder. Your job is to capture decisions that will guide research and planning, not to figure out implementation yourself.
+</purpose>
+
+<downstream_awareness>
+**CONTEXT.md feeds into:**
+
+1. **grd-phase-researcher** — Reads CONTEXT.md to know WHAT to research
+2. **grd-planner** — Reads CONTEXT.md to know WHAT decisions are locked
+
+**Your job:** Capture decisions clearly enough that downstream agents can act on them without asking the user again.
+</downstream_awareness>
+
+<process>
+
+<step name="initialize" priority="first">
+Phase number from argument (required).
+
+```bash
+INIT=$(node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js init phase-op "${PHASE}")
+```
+
+Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `has_verification`, `plan_count`, `roadmap_exists`, `planning_exists`.
+
+**If `phase_found` is false:**
+```
+Phase [X] not found in roadmap.
+
+Use /grd:progress to see available phases.
+```
+Exit workflow.
+</step>
+
+<step name="check_existing">
+Check if CONTEXT.md already exists using `has_context` from init.
+
+**If exists:**
+Use AskUserQuestion:
+- header: "Existing context"
+- question: "Phase [X] already has context. What do you want to do?"
+- options:
+  - "Update it" — Review and revise existing context
+  - "View it" — Show me what's there
+  - "Skip" — Use existing context as-is
+</step>
+
+<step name="analyze_phase">
+Analyze the phase to identify gray areas worth discussing. Read the phase description from ROADMAP.md and determine:
+
+1. **Domain boundary** — What capability is this phase delivering?
+2. **Gray areas by category** — For each relevant category, identify 1-2 specific ambiguities
+3. **Skip assessment** — If no meaningful gray areas exist, the phase may not need discussion
+</step>
+
+<step name="present_gray_areas">
+Present the domain boundary and gray areas to user.
+
+**First, state the boundary:**
+```
+Phase [X]: [Name]
+Domain: [What this phase delivers]
+
+We'll clarify HOW to implement this.
+(New capabilities belong in other phases.)
+```
+
+**Then use AskUserQuestion (multiSelect: true):**
+- header: "Discuss"
+- question: "Which areas do you want to discuss for [phase name]?"
+- options: Generate 3-4 phase-specific gray areas
+</step>
+
+<step name="discuss_areas">
+For each selected area, conduct a focused discussion loop.
+
+**CRITICAL: No solutions before understanding.** You are gathering context, not solving problems. Do not propose approaches until you fully understand the problem space. Premature solutions anchor thinking and close off better options.
+
+**Protocol:**
+
+1. Ask questions **ONE AT A TIME**. Each answer informs the next question. Never batch multiple questions — it overwhelms and produces shallow answers.
+
+2. After 4 questions per area, offer a check:
+   - Use AskUserQuestion:
+     - header: "Direction"
+     - question: "We've explored [area]. What next?"
+     - options:
+       - "Go deeper" — More questions on this area
+       - "Propose approaches" — I've shared enough, show me options
+       - "Skip" — Move to next area
+
+3. **If "Go deeper"**: Ask 4 more questions, then check again.
+
+4. **If "Propose approaches"**: Enter approach proposal mode (see `propose_approaches` sub-step below).
+
+5. **If "Skip"**: Move to next selected area.
+
+**Anti-patterns to avoid:**
+- Solution anchoring ("Should we use a transformer here?")
+- Leading questions ("Don't you think X would work?")
+- Premature trade-off analysis
+- Skipping the "why" to jump to "how"
+- Question batching
+- Assumption embedding ("How should we implement the cache?" assumes caching is needed)
+</step>
+
+<step name="propose_approaches">
+When user selects "Propose approaches" during discussion:
+
+Present 2-3 **distinct** approaches (not minor variations). For each:
+- **What it is** (1-2 sentences)
+- **Research backing** (paper references from LANDSCAPE.md/PAPERS.md if applicable)
+- **Complexity** (low / medium / high)
+- **Risk** (what could go wrong)
+- **Trade-offs** vs alternatives
+
+Use AskUserQuestion for selection:
+- header: "Approach"
+- question: "Which approach for [area]?"
+- options: the approaches + "Combine elements" + "None — explore more"
+
+**If "Combine elements"**: Ask which elements from which approaches, then synthesize.
+**If "None — explore more"**: Return to questioning loop.
+**Otherwise**: Record selection with rationale.
+</step>
+
+<step name="write_context">
+Create CONTEXT.md capturing decisions made.
+
+**File location:** `${phase_dir}/${padded_phase}-CONTEXT.md`
+
+Structure with: Phase Boundary, Implementation Decisions, Approach Selections (if any approaches were proposed and selected), Claude's Discretion, Specific Ideas, Deferred Ideas.
+</step>
+
+<step name="confirm_creation">
+Present summary and next steps:
+
+```
+Created: ${phase_dir}/${PADDED_PHASE}-CONTEXT.md
+
+## Decisions Captured
+
+### [Category]
+- [Key decision]
+
+---
+
+## Next Up
+
+**Phase ${PHASE}: [Name]** — [Goal from ROADMAP.md]
+
+`/grd:plan-phase ${PHASE}`
+
+<sub>`/clear` first -> fresh context window</sub>
+
+---
+
+**Also available:**
+- `/grd:plan-phase ${PHASE} --skip-research` — plan without research
+- Review/edit CONTEXT.md before continuing
+
+---
+```
+</step>
+
+<step name="git_commit">
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/grd-tools.js commit "docs(${padded_phase}): capture phase context" --files "${phase_dir}/${padded_phase}-CONTEXT.md"
+```
+</step>
+
+</process>
+
+<success_criteria>
+- Phase validated against roadmap
+- Gray areas identified through intelligent analysis
+- User selected which areas to discuss
+- Each selected area explored until user satisfied
+- Scope creep redirected to deferred ideas
+- CONTEXT.md captures actual decisions
+- User knows next steps
+</success_criteria>

package/commands/discuss.md

@@ -0,0 +1,55 @@
+---
+description: Run an ad-hoc multi-backend discussion on a topic
+argument-hint: <topic>
+---
+
+<purpose>
+Run a multi-backend discussion using configured participants. Each backend contributes a perspective, a synthesizer backend summarizes the round, and the result is written to the discussion history. Useful for getting diverse AI perspectives on architecture decisions, design questions, or open-ended research topics.
+</purpose>
+
+<process>
+
+<step name="resolve_topic">
+If an argument was provided, use it as the discussion topic.
+
+If no argument was provided, read `.planning/ROADMAP.md` to identify the current phase goal and use it as the topic:
+```
+"What is the best approach for the current phase goal: [goal from ROADMAP.md]?"
+```
+</step>
+
+<step name="run_discussion">
+Call the `grd_discussion_run` MCP tool with the topic:
+
+```
+grd_discussion_run(
+  topic: <resolved topic>,
+  // participants: omit to use all available backends from config
+  // rounds: omit to use default (2)
+  // synthesizer: omit to use default (claude)
+)
+```
+
+The tool dispatches to all configured participants sequentially (from `backend_roles` in config, or all available backends), runs the configured number of rounds, and synthesizes a final answer.
+</step>
+
+<step name="present_results">
+Present the discussion results clearly:
+
+1. **Participants** — List which backends participated vs were skipped (unavailable)
+2. **Round responses** — For each round, show each backend's name and a brief excerpt (first 200 chars) of their response
+3. **Synthesis** — Show the synthesizer's full response prominently under a `## Synthesis` header
+4. **History file** — Report the path to the saved discussion markdown file (`discussion_file` field in result)
+
+If a backend was skipped (not available on PATH), note it as "skipped — not available".
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Topic resolved (from argument or current phase goal)
+- [ ] grd_discussion_run tool called with topic
+- [ ] Round responses presented with backend names
+- [ ] Synthesis displayed prominently
+- [ ] History file path reported
+</success_criteria>