From 08539ffd45fa005e1d3838f306c6c563bdec6a72 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Mon, 15 Dec 2025 21:33:06 -0600 Subject: [PATCH] feat(02-02): research subagent prompt templates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Created comprehensive prompts for ecosystem, architecture, pitfalls, standards - Updated workflow with required_reading and concrete Task tool examples - Batch ordering: ecosystem+architecture first, pitfalls+standards second 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .../references/research-subagent-prompts.md | 557 ++++++++++++++++++ get-shit-done/workflows/research-project.md | 40 +- 2 files changed, 586 insertions(+), 11 deletions(-) create mode 100644 get-shit-done/references/research-subagent-prompts.md diff --git a/get-shit-done/references/research-subagent-prompts.md b/get-shit-done/references/research-subagent-prompts.md new file mode 100644 index 000000000..f46b9c04c --- /dev/null +++ b/get-shit-done/references/research-subagent-prompts.md @@ -0,0 +1,557 @@ +# Research Subagent Prompts + + +Prompt templates for subagents that research domain ecosystems before roadmap creation. + +Each subagent: +- Researches ONE category (ecosystem, architecture, pitfalls, or standards) +- Writes directly to `.planning/research/{category}.md` +- Uses WebSearch and Context7 for current information +- Cross-verifies findings with authoritative sources + +These prompts are used by the research-project workflow when spawning Task tool subagents. + + + +## Ecosystem Research Subagent + +Use this template for spawning ecosystem research subagents: + +``` + +## Objective +Research the library/framework ecosystem for {domain} and write findings to .planning/research/ecosystem.md + +## Domain Context +{Paste relevant sections from PROJECT.md describing what's being built} + +## Your Assignment +File: .planning/research/ecosystem.md +Category: ecosystem +Purpose: Map the libraries, frameworks, and tools available for this domain + +## Research Questions +Answer these questions through web research: +1. What are the go-to libraries for this problem space? +2. Which frameworks are actively maintained (commits in last 12 months)? +3. What's the "standard stack" that domain experts use? +4. What should NOT be hand-rolled because existing solutions exist? +5. What are the version requirements and compatibility considerations? + +## Research Requirements + +You MUST use WebSearch and Context7 to get current information. + +For EACH library/tool discovered: +1. Verify actively maintained (GitHub commits in last 12 months) +2. Get current version number +3. Understand when to use vs alternatives +4. Find official documentation and getting started guides +5. Note any critical dependencies or compatibility issues + +**Search queries to run:** +- "{domain} best libraries 2024 2025" +- "{domain} framework comparison" +- "{specific problem from PROJECT.md} library recommendation" +- "{domain} standard stack production" + +**Red flags (reject these):** +- No updates in 12+ months +- Deprecated or archived repositories +- Pre-2023 recommendations without verification + +## Output Format + +Write to .planning/research/ecosystem.md using this structure: + +# Ecosystem: {Domain} + +**Category:** ecosystem +**Domain:** {domain} +**Researched:** {today's date} +**Confidence:** {high | medium | low} + +## Research Summary + +{2-3 sentences on what was found and the recommended direction} + +## Findings + +### {Library/Framework 1} + +{What it is and what it does} + +**Source:** {URL} +**Version:** {current version} +**Confidence:** {high | medium | low} +**Why consider:** {Relevance to project} +**Tradeoffs:** {Limitations or considerations} + +### {Library/Framework 2} + +{Same structure} + +{... continue for each significant option ...} + +## Recommendations + +### Use + +- **{Library A}** - {One-line reason, specific use case} +- **{Library B}** - {One-line reason, specific use case} + +### Avoid + +- **{Library X}** - {One-line reason} +- **Hand-rolling {Y}** - {Existing solution available} + +### Defer Decision + +- **{Topic}** - {Why more investigation needed} + +## Sources + +| Source | Type | Confidence | Last Verified | +|--------|------|------------|---------------| +| {URL} | {official docs / github / blog} | {high/medium/low} | {today} | + +## Open Questions + +- {Question that couldn't be resolved} +- {Question for roadmap planning} + +--- +*Generated by research-project subagent* +*Category: ecosystem* + +## Quality Criteria +- Include at least 3-5 library/framework options +- Compare options (don't just list them) +- Every recommendation has a specific reason +- Verify all versions are current +- Note what NOT to hand-roll + +``` + + + +## Architecture Research Subagent + +Use this template for spawning architecture research subagents: + +``` + +## Objective +Research architecture patterns for {domain} projects and write findings to .planning/research/architecture.md + +## Domain Context +{Paste relevant sections from PROJECT.md describing what's being built} + +## Your Assignment +File: .planning/research/architecture.md +Category: architecture +Purpose: Document standard project structure and architectural patterns + +## Research Questions +Answer these questions through web research: +1. How do experts structure projects in this domain? +2. What component boundaries work best? +3. What patterns prevent common problems? +4. How does data flow in typical implementations? +5. What directory structure do production projects use? + +## Research Requirements + +You MUST use WebSearch and Context7 to get current information. + +For EACH pattern discovered: +1. Find real-world examples (GitHub repos, case studies) +2. Understand the tradeoffs +3. Note when it applies vs when it doesn't +4. Find implementation guidelines + +**Search queries to run:** +- "{domain} project structure best practices" +- "{domain} architecture patterns" +- "{specific problem from PROJECT.md} implementation patterns" +- "{domain} component organization" +- "{domain} example github repo structure" + +## Output Format + +Write to .planning/research/architecture.md using this structure: + +# Architecture: {Domain} + +**Category:** architecture +**Domain:** {domain} +**Researched:** {today's date} +**Confidence:** {high | medium | low} + +## Research Summary + +{2-3 sentences on recommended architectural approach} + +## Findings + +### Project Structure + +Recommended directory layout: +``` +{concrete directory structure with comments} +``` + +**Source:** {Reference project or documentation} +**Rationale:** {Why this structure works} + +### {Pattern 1 Name} + +**When to use:** {Specific scenarios} +**Implementation:** {How to implement} +**Example:** {Concrete code example if applicable} +**Tradeoffs:** {What you give up} + +### {Pattern 2 Name} + +{Same structure} + +### Data Flow + +{How data moves through the system} + +### Component Boundaries + +{What should be separate vs combined} + +## Recommendations + +### Adopt + +- **{Pattern A}** - {Why it fits this project} +- **{Structure B}** - {Why it fits this project} + +### Avoid + +- **{Anti-pattern X}** - {Why it fails} +- **{Premature abstraction Y}** - {Why to defer} + +## Sources + +| Source | Type | Confidence | Last Verified | +|--------|------|------------|---------------| +| {URL} | {official docs / github / tutorial} | {high/medium/low} | {today} | + +## Open Questions + +- {Architecture decision that needs more context} +- {Question about project-specific constraints} + +--- +*Generated by research-project subagent* +*Category: architecture* + +## Quality Criteria +- Include concrete directory structure +- Document at least 2-3 patterns +- Every recommendation has specific rationale +- Include real example sources +- Address data flow and component boundaries + +``` + + + +## Pitfalls Research Subagent + +Use this template for spawning pitfalls research subagents: + +``` + +## Objective +Research common mistakes and pitfalls in {domain} projects and write findings to .planning/research/pitfalls.md + +## Domain Context +{Paste relevant sections from PROJECT.md describing what's being built} + +## Your Assignment +File: .planning/research/pitfalls.md +Category: pitfalls +Purpose: Catalog what NOT to do and why + +## Research Questions +Answer these questions through web research: +1. What mistakes do beginners commonly make in this domain? +2. What causes performance problems? +3. What architectural choices lead to regret? +4. What seems like a good idea but isn't? +5. What are the debugging nightmares people warn about? + +## Research Requirements + +You MUST use WebSearch and Context7 to get current information. + +For EACH pitfall discovered: +1. Find real examples (Stack Overflow, GitHub issues, blog posts) +2. Understand the root cause +3. Find the correct approach +4. Note detection methods (how to know if you're doing this) + +**Search queries to run:** +- "{domain} common mistakes" +- "{domain} things I wish I knew" +- "{domain} performance problems" +- "{domain} debugging nightmare" +- "{specific technology} gotchas" +- "{domain} anti-patterns" + +## Output Format + +Write to .planning/research/pitfalls.md using this structure: + +# Pitfalls: {Domain} + +**Category:** pitfalls +**Domain:** {domain} +**Researched:** {today's date} +**Confidence:** {high | medium | low} + +## Research Summary + +{2-3 sentences on the most critical pitfalls to avoid} + +## Findings + +### {Pitfall 1: Descriptive Name} + +**Problem:** {What people do wrong} +**Why it happens:** {Root cause or common misconception} +**Consequence:** {What goes wrong} +**Detection:** {How to know if you're doing this} +**Prevention:** {Correct approach} + +**Source:** {URL with real example} +**Severity:** {high | medium | low} + +### {Pitfall 2: Descriptive Name} + +{Same structure} + +{... continue for each significant pitfall ...} + +## Recommendations + +### Critical Pitfalls (Must Avoid) + +1. **{Pitfall A}** - {One-line why it's critical} +2. **{Pitfall B}** - {One-line why it's critical} + +### Common But Recoverable + +- **{Pitfall C}** - {Can be fixed if caught early} + +### Easy Wins + +- **{Prevention D}** - {Simple thing that prevents problems} + +## Sources + +| Source | Type | Confidence | Last Verified | +|--------|------|------------|---------------| +| {URL} | {stack overflow / github issue / blog} | {high/medium/low} | {today} | + +## Open Questions + +- {Potential pitfall that needs more context} +- {Question about project-specific risks} + +--- +*Generated by research-project subagent* +*Category: pitfalls* + +## Quality Criteria +- Include at least 5-7 pitfalls +- Categorize by severity +- Every pitfall has prevention/solution +- Include real examples with sources +- Focus on domain-specific issues (not generic coding advice) + +``` + + + +## Standards Research Subagent + +Use this template for spawning standards research subagents: + +``` + +## Objective +Research best practices and quality standards for {domain} projects and write findings to .planning/research/standards.md + +## Domain Context +{Paste relevant sections from PROJECT.md describing what's being built} + +## Your Assignment +File: .planning/research/standards.md +Category: standards +Purpose: Document best practices, conventions, and quality expectations + +## Research Questions +Answer these questions through web research: +1. What does "production quality" mean for this domain? +2. What testing approaches work for this type of project? +3. What performance benchmarks matter? +4. What accessibility/security considerations apply? +5. What conventions do experts follow? + +## Research Requirements + +You MUST use WebSearch and Context7 to get current information. + +For EACH standard discovered: +1. Find authoritative sources (official docs, style guides) +2. Understand the rationale +3. Find measurable criteria where possible +4. Note enforcement tools if available + +**Search queries to run:** +- "{domain} best practices 2024 2025" +- "{domain} style guide" +- "{domain} testing strategy" +- "{domain} performance benchmarks" +- "{domain} production checklist" +- "{domain} code quality standards" + +## Output Format + +Write to .planning/research/standards.md using this structure: + +# Standards: {Domain} + +**Category:** standards +**Domain:** {domain} +**Researched:** {today's date} +**Confidence:** {high | medium | low} + +## Research Summary + +{2-3 sentences on key quality standards for this project} + +## Findings + +### Code Quality + +**Conventions:** +- {Naming conventions} +- {Formatting standards} +- {Organization patterns} + +**Tools:** {Linters, formatters, static analysis} +**Source:** {URL} + +### Testing Standards + +**Strategy:** {How to test this type of project} +**Coverage expectations:** {What to test, what's overkill} +**Tools:** {Testing frameworks and utilities} + +**Source:** {URL} + +### Performance Standards + +**Benchmarks:** {What metrics matter} +**Targets:** {Specific numbers if applicable} +**Measurement:** {How to test} + +**Source:** {URL} + +### {Domain-Specific Standard} + +{Standards specific to this domain} + +## Recommendations + +### Adopt + +- **{Standard A}** - {Why it applies} +- **{Convention B}** - {Why it matters} + +### Skip (Over-Engineering) + +- **{Standard X}** - {Why not needed for this project} + +### Defer + +- **{Standard Y}** - {Consider after MVP} + +## Sources + +| Source | Type | Confidence | Last Verified | +|--------|------|------------|---------------| +| {URL} | {official docs / style guide / blog} | {high/medium/low} | {today} | + +## Open Questions + +- {Standard that depends on project scale} +- {Question about appropriate rigor level} + +--- +*Generated by research-project subagent* +*Category: standards* + +## Quality Criteria +- Cover code quality, testing, and performance +- Include measurable criteria where possible +- Distinguish must-haves from nice-to-haves +- Reference authoritative sources +- Be realistic about project scope (not enterprise overkill) + +``` + + + +## Using the Task Tool + +When spawning research subagents, use the Task tool with: +- `subagent_type`: "general-purpose" +- `prompt`: The filled-in template above +- `description`: Brief description like "Research ecosystem for {domain}" + +**Batching strategy:** + +Spawn 3-4 Task calls in a SINGLE message. Wait for all to complete before next batch. + +``` +[Message 1: Batch 1] +Task: Research ecosystem for {domain} +Task: Research architecture for {domain} +[Wait for completion] + +[Message 2: Batch 2] +Task: Research pitfalls for {domain} +Task: Research standards for {domain} +[Wait for completion] +``` + +**Batch ordering rationale:** +- Batch 1 (ecosystem + architecture): Core understanding of what to build and how +- Batch 2 (pitfalls + standards): Refinements that build on core understanding + +**After all batches complete:** +1. Verify all 4 files exist in .planning/research/ +2. Extract key findings for summary +3. Present next steps to user + + + +## Subagent Quality Verification + +After subagents complete, verify: + +- [ ] All 4 files exist in .planning/research/ +- [ ] Each file has substantive content (not stub/error) +- [ ] Recommendations are specific (not "it depends") +- [ ] Sources are cited with confidence levels +- [ ] Information is current (2024-2025 sources preferred) +- [ ] Open questions are honest about gaps + diff --git a/get-shit-done/workflows/research-project.md b/get-shit-done/workflows/research-project.md index 1a5164758..4e8401c8f 100644 --- a/get-shit-done/workflows/research-project.md +++ b/get-shit-done/workflows/research-project.md @@ -5,6 +5,12 @@ Subagents write directly to `.planning/research/` to preserve main context. Maximum 4 parallel subagents, recommended batch size 3. + +**Read before executing:** +1. `~/.claude/get-shit-done/references/research-subagent-prompts.md` - Prompt templates for each category +2. `~/.claude/get-shit-done/templates/project-research.md` - Output format subagents use + + @@ -34,33 +40,45 @@ Each subagent researches ONE category and writes directly to `.planning/research ## Batched Subagent Spawning +Read prompt templates from `~/.claude/get-shit-done/references/research-subagent-prompts.md` + **Batch 1: Foundation research** (spawn in parallel) Spawn using Task tool with `subagent_type="general-purpose"`: ``` -Subagent 1: ecosystem.md -Subagent 2: architecture.md +Task 1: + description: "Research ecosystem for {domain}" + prompt: [ecosystem_subagent_prompt template filled with PROJECT.md context] + +Task 2: + description: "Research architecture for {domain}" + prompt: [architecture_subagent_prompt template filled with PROJECT.md context] ``` -**Wait for Batch 1 completion.** +Send BOTH Task calls in a single message. Wait for Batch 1 completion. **Batch 2: Risk & quality research** (spawn in parallel) ``` -Subagent 3: pitfalls.md -Subagent 4: standards.md +Task 3: + description: "Research pitfalls for {domain}" + prompt: [pitfalls_subagent_prompt template filled with PROJECT.md context] + +Task 4: + description: "Research standards for {domain}" + prompt: [standards_subagent_prompt template filled with PROJECT.md context] ``` -**Wait for Batch 2 completion.** +Send BOTH Task calls in a single message. Wait for Batch 2 completion. -**Subagent prompt structure:** +**Batch ordering rationale:** +- Batch 1 (ecosystem + architecture): Core understanding of what to build and how +- Batch 2 (pitfalls + standards): Refinements that build on core understanding -Use prompts from `~/.claude/get-shit-done/references/research-subagent-prompts.md` - -Each subagent receives: +**Each subagent receives:** - Domain context from PROJECT.md -- Category assignment (ecosystem, architecture, etc.) +- Category assignment (ecosystem, architecture, pitfalls, standards) - Output format from templates/project-research.md - Instruction to write directly to `.planning/research/{category}.md`