Initial commit

2025-11-29 18:22:50 +08:00
commit e6ac7edfc0
14 changed files with 2164 additions and 0 deletions
--- a/commands/research-codebase.md
+++ b/commands/research-codebase.md
@@ -0,0 +1,185 @@
+---
+name: research-codebase
+description: Conduct comprehensive codebase research using parallel sub-agents to answer questions and document findings
+---
+
+# 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, 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.
+
+## Process
+
+1. **Evaluate if any available skill is relevant and a fit for the task**:
+   - If so, respond with:
+```I believe the [skill name] skill is well-suited to assist with this research. It provides expertise in [skill description]. I will leverage this skill throughout process to ensure we follow best practices and produce a high-quality research.
+```
+
+2. **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
+
+3. **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
+
+4. **Spawn parallel sub-agent tasks for comprehensive research:**
+   - Create multiple Task agents to research different aspects concurrently
+
+   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
+   - Don't write detailed prompts about HOW to search - the agents already know
+
+5. **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 (both codebase and thoughts findings)
+   - Prioritize live codebase findings as primary source of truth
+   - Use thoughts/ findings as supplementary historical context
+   - Connect findings across different components
+   - Include specific file paths and line numbers for reference
+   - Verify all thoughts/ paths are correct (e.g., thoughts/allison/ not thoughts/shared/ for personal files)
+   - Highlight patterns, connections, and architectural decisions
+   - Answer the user's specific questions with concrete evidence
+
+6. **Gather metadata for the research document:**
+   - generate all relevant metadata
+   - Filename: `thoughts/shared/research/YYYY-MM-DD-ENG-XXXX-description.md`
+     - Format: `YYYY-MM-DD-ENG-XXXX-description.md` where:
+       - YYYY-MM-DD is today's date
+       - ENG-XXXX is the ticket number (omit if no ticket)
+       - description is a brief kebab-case description of the research topic
+     - Examples:
+       - With ticket: `2025-01-08-ENG-1478-parent-child-tracking.md`
+       - Without ticket: `2025-01-08-authentication-flow.md`
+
+7. **Generate research document:**
+   - Use the metadata gathered in step 4
+   - Structure the document with YAML frontmatter followed by content:
+     ```markdown
+     ---
+     date: [Current date and time with timezone in ISO format]
+     researcher: [Researcher name]
+     git_commit: [Current commit hash]
+     branch: [Current branch name]
+     repository: [Repository name]
+     topic: "[User's Question/Topic]"
+     tags: [research, codebase, relevant-component-names]
+     status: complete
+     last_updated: [Current date in YYYY-MM-DD format]
+     last_updated_by: [Researcher name]
+     ---
+
+     # Research: [User's Question/Topic]
+
+     **Date**: [Current date and time with timezone from step 4]
+     **Researcher**: [Researcher name]
+     **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 (from thoughts/)
+     [Relevant insights from thoughts/ directory with references]
+     - `thoughts/shared/something.md` - Historical decision about X
+     - `thoughts/local/notes.md` - Past exploration of Y
+     Note: Paths exclude "searchable/" even if found there
+
+     ## Related Research
+     [Links to other research documents in thoughts/shared/research/]
+
+     ## Open Questions
+     [Any areas that need further investigation]
+     ```
+
+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/{owner}/{repo}/blob/{commit}/{file}#L{line}`
+   - Replace local file references with permalinks in the document
+
+9. **Sync and 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 and syncing
+
+## 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 thoughts/ directory provides historical context to supplement live findings
+- Focus on finding concrete file paths and line numbers for developer reference
+- 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
+- Encourage sub-agents to find examples and usage patterns, not just definitions
+- Explore all of thoughts/ 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
+- **Path handling**: The thoughts/searchable/ directory contains hard links for searching
+  - Always document paths by removing ONLY "searchable/" - preserve all other subdirectories
+  - Examples of correct transformations:
+    - `thoughts/searchable/allison/old_stuff/notes.md` → `thoughts/allison/old_stuff/notes.md`
+    - `thoughts/searchable/shared/prs/123.md` → `thoughts/shared/prs/123.md`
+    - `thoughts/searchable/global/shared/templates.md` → `thoughts/global/shared/templates.md`
+  - NEVER change allison/ to shared/ or vice versa - preserve the exact directory structure
+  - 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
+  - Format the research document for 80-character line width for readability