zhongwei/gh-mchowning-claude-code-plugins-workflow-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:39:44 +08:00
commit 287a80287f
18 changed files with 2362 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

200
commands/create-research-doc.md Normal file
View File

@@ -0,0 +1,200 @@
# Research Codebase
You are tasked with conducting comprehensive research across the codebase to answer user questions by spawning parallel sub-agents and synthesizing their findings.
## Initial Setup:
When this command is invoked, if you already think you know what the user wants to research, confirm that with the user. If you do not know, respond with:
```
I'm ready to research the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections.
```
Then wait for the user's research query.
## Steps to follow after receiving the research query:
1. **Read any directly mentioned files first:**
- If the user mentions specific files (tickets, docs, JSON), read them FULLY first
- **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
- **CRITICAL**: Read these files yourself in the main context before spawning any sub-tasks
- This ensures you have full context before decomposing the research
2. **Analyze and decompose the research question:**
- Break down the user's query into composable research areas
- Take time to ultrathink about the underlying patterns, connections, and architectural implications the user might be seeking
- Identify specific components, patterns, or concepts to investigate
- Create a research plan using TodoWrite to track all subtasks
- Consider which directories, files, or architectural patterns are relevant
3. **Spawn parallel sub-agent tasks for comprehensive research:**
- Create multiple Task agents to research different aspects concurrently
- We now have specialized agents that know how to do specific research tasks:
**For codebase research:**
- Use the `workflow-tools:codebase-locator` agent to find WHERE files and components live
- Use the `workflow-tools:codebase-analyzer` agent to understand HOW specific code works
- Use the `workflow-tools:codebase-pattern-finder` agent if you need examples of similar implementations
**For `working-notes/` directory:**
- Use the `workflow-tools:notes-locator` agent to discover what documents exist about the topic
- Use the `workflow-tools:notes-analyzer` agent to extract key insights from specific documents (only the most relevant ones)
**For web research:**
- Use the `workflow-tools:web-search-researcher` agent for external documentation and resources
- Instruct the agent to return LINKS with their findings, and please INCLUDE those links in your final report
**For historical context:**
- Use the `workflow-tools:jira-searcher` agent to search for relevant Jira issues that may provide business context
- Use the `workflow-tools:git-history` agent to search git history, PRs, and PR comments for implementation context and technical decisions
The key is to use these agents intelligently:
- Start with locator agents to find what exists
- Then use analyzer agents on the most promising findings
- Run multiple agents in parallel when they're searching for different things
- Each agent knows its job - just tell it what you're looking for
- Do NOT write detailed prompts about HOW to search - the agents already know
4. **Wait for all sub-agents to complete and synthesize findings:**
- IMPORTANT: Wait for ALL sub-agent tasks to complete before proceeding
- Compile all sub-agent results (codebase, `working-notes/` findings, and web research)
- Prioritize live codebase findings as primary source of truth
- Use `working-notes/` findings as supplementary historical context
- Connect findings across different components
- Include specific file paths and line numbers for reference
- Highlight patterns, connections, and architectural decisions
- Answer the user's specific questions with concrete evidence
5. **Gather metadata for the research document:**
- Filename: `working-notes/{YYYY-MM-DD}_research_[descriptive-name].md`. Use `date '+%Y-%m-%d'` for the timestamp in the filename.
- Use the `workflow-tools:frontmatter-generator` agent to collect metadata.
- Wait for the agent to return metadata before proceeding.
6. **Generate research document:**
- Use the metadata gathered in the previous step
- Structure the document with YAML frontmatter followed by content:
```markdown
---
date: [Current date and time with timezone in ISO format]
git_commit: [Current commit hash]
branch: [Current branch name]
repository: [Repository name]
topic: "[User's Question/Topic]"
tags: [research, codebase, relevant-component-names]
last_updated: [Current date in YYYY-MM-DD format]
---
# Research: [User's Question/Topic]
**Date**: [Current date and time with timezone from step 4]
**Git Commit**: [Current commit hash from step 4]
**Branch**: [Current branch name from step 4]
**Repository**: [Repository name]
## Research Question
[Original user query]
## Summary
[High-level findings answering the user's question]
## Detailed Findings
### [Component/Area 1]
- Finding with reference ([file.ext:line](link))
- Connection to other components
- Implementation details
### [Component/Area 2]
...
## Code References
- `path/to/file.py:123` - Description of what's there
- `another/file.ts:45-67` - Description of the code block
## Architecture Insights
[Patterns, conventions, and design decisions discovered]
## Historical Context
[Relevant insights from `working-notes/` directory and any relevant Jira issues. Include references for all insights.]
## Related Research
[Links to past research documents in `working-notes/`]
## Open Questions
[Any areas that need further investigation]
```
7. **Automatic External Review (Internal Quality Check):**
- Check for external review environment variable: `bash -c 'echo ${CLAUDE_EXTERNAL_REVIEW_COMMAND:-NOT_SET}'`
- **If environment variable IS set:**
- Invoke the external review command with the comprehensive review prompt (from review-doc.md step 4) for the just-created research document
- **Critically analyze the feedback with a VERY skeptical lens**:
- Dismiss theoretical concerns that don't apply to this specific research
- Ignore feedback that adds unnecessary complexity
- Only identify feedback that reveals genuine gaps or errors
- **Silently address ONLY critical issues**:
- Fix any factual errors or missing critical information in the document
- Add only truly important missing considerations
- Make minimal, focused updates - do NOT implement every suggestion
- **Do NOT present the review to the user** - this is an internal quality check
- **If environment variable is NOT set:**
- Skip this step and proceed to adding GitHub permalinks
8. **Add GitHub permalinks (if applicable):**
- Check if on main branch or if commit is pushed: `git branch --show-current` and `git status`
- If on main/master or pushed, generate GitHub permalinks:
- Get repo info: `gh repo view --json owner,name`
- Create permalinks: `https://github.com/{}/{repo}/blob/{commit}/{file}#L{line}`
- Replace local file references with permalinks in the document
9. **Present findings:**
- Present a concise summary of findings to the user
- Include key file references for easy navigation
- Ask if they have follow-up questions or need clarification
10. **Handle follow-up questions:**
- If the user has follow-up questions, append to the same research document
- Update the frontmatter fields `last_updated` and `last_updated_by` to reflect the update
- Add `last_updated_note: "Added follow-up research for [brief description]"` to frontmatter
- Add a new section: `## Follow-up Research [timestamp]`
- Spawn new sub-agents as needed for additional investigation
- Continue updating the document
## Important notes:
- Always use parallel Task agents to maximize efficiency and minimize context usage
- Always run fresh codebase research - never rely solely on existing research documents
- The `working-notes/` directory provides historical context to supplement live findings
- Focus on finding concrete file paths and line numbers for developer reference
- The research document should NOT include any references to how long things will take (i.e., Phase 1 will take 2 days)
- Research documents should be self-contained with all necessary context
- Each sub-agent prompt should be specific and focused on read-only operations
- Consider cross-component connections and architectural patterns
- Include temporal context (when the research was conducted)
- Link to GitHub when possible for permanent references
- Keep the main agent focused on synthesis, not deep file reading. Use subagents for any deep file reading.
- Encourage sub-agents to find examples and usage patterns, not just definitions
- Explore all of `working-notes/` directory, not just research subdirectory
- **File reading**: Always read mentioned files FULLY (no limit/offset) before spawning sub-tasks
- **Critical ordering**: Follow the numbered steps exactly
- ALWAYS read mentioned files first before spawning sub-tasks (step 1)
- ALWAYS wait for all sub-agents to complete before synthesizing (step 4)
- ALWAYS gather metadata before writing the document (step 5 before step 6)
- NEVER write the research document with placeholder values
- This ensures paths are correct for editing and navigation
- **Frontmatter consistency**:
- Always include frontmatter at the beginning of research documents
- Keep frontmatter fields consistent across all research documents
- Update frontmatter when adding follow-up research
- Use snake_case for multi-word field names (e.g., `last_updated`, `git_commit`)
- Tags should be relevant to the research topic and components studied