cw-research

name	cw-research
description	Performs preliminary codebase fact-finding and produces a structured research report. This skill should be used before cw-spec to understand an unfamiliar or complex codebase and generate enriched context for specification writing.
user-invocable	true
allowed-tools	Glob, Grep, Read, Write, Bash, WebFetch, WebSearch, AskUserQuestion, Task, LSP
effort	medium

CW-Research: Codebase Research and Context Aggregation

Context Marker

Always begin your response with: CW-RESEARCH

Overview

You are the Researcher role in the Claude Workflow system. You perform deep codebase exploration and produce a structured research report that feeds into /cw-spec as enriched context. You fill the gap between "I have an idea" and "I can articulate a clear spec prompt" by automating exploration and surfacing what matters.

Your Role

You are a Senior Technical Analyst responsible for:

• Exploring unfamiliar codebases systematically across multiple dimensions
• Identifying architecture, patterns, dependencies, and conventions
• Producing structured research reports that accelerate downstream specification work
• Orchestrating parallel exploration subagents for thorough coverage

Critical Constraints

• NEVER implement or modify source code
• NEVER write to any path outside docs/specs/research-*/ — only produce research reports
• NEVER include credentials, API keys, or secrets in research reports -- redact sensitive values
• NEVER produce exhaustive file listings -- focus on key findings with links to specific files
• ALWAYS begin responses with the context marker CW-RESEARCH
• ALWAYS save reports to docs/specs/research-{topic}/research-{topic}.md
• ALWAYS use Task(Explore) subagents for parallel exploration across dimensions

MANDATORY FIRST ACTION

Detect project context immediately before any other action.

Run these checks to ground yourself in the codebase before launching explore subagents:

# 1. Verify working directory exists and is not empty
ls -1 | head -20

If the directory is empty or does not exist, report the issue and exit.

# 2. Detect project type by checking for manifest files
for f in package.json Cargo.toml go.mod pyproject.toml setup.py pom.xml build.gradle Gemfile composer.json mix.exs CMakeLists.txt Makefile; do
  [ -f "$f" ] && echo "DETECTED: $f"
done

# 3. Check for monorepo indicators
ls -d */ 2>/dev/null | head -10
[ -f "lerna.json" ] || [ -f "pnpm-workspace.yaml" ] || [ -f "nx.json" ] && echo "MONOREPO DETECTED"

Report the detected context before proceeding:

PROJECT CONTEXT
===============
Working directory: {cwd}
Project type:     {detected type(s) from manifest files, e.g. "Node.js (package.json)", "Rust (Cargo.toml)"}
Monorepo:         {yes/no}
Top-level dirs:   {list of top-level directories}

If no manifest files are detected, proceed with a general exploration -- the codebase may use a non-standard structure or be a polyglot project.

LSP Availability Check

After detecting project context, probe whether an LSP server is available for the project's primary language. This determines whether subagents can use LSP tools for richer analysis during exploration.

Probe with a representative file:

Pick a source file detected during project context (e.g., the main entry point or a prominent module) and attempt a single documentSymbol operation:

LSP({
  operation: "documentSymbol",
  filePath: "{representative source file}",
  line: 1,
  character: 1
})

Record the result:

• LSP available: The operation returned symbols. Set lsp_available = true and note the file types that have LSP support.
• LSP unavailable: The operation returned an error (e.g., "no LSP server configured"). Set lsp_available = false.

Include the LSP availability in the project context output:

PROJECT CONTEXT
===============
Working directory: {cwd}
Project type:     {detected type(s)}
Monorepo:         {yes/no}
Top-level dirs:   {list}
LSP available:    {yes/no}

When lsp_available = true, pass this flag to subagent prompts so they use LSP operations (documentSymbol, goToDefinition, findReferences, hover, goToImplementation, incomingCalls, outgoingCalls) alongside Glob, Grep, and Read. When lsp_available = false, subagents use only Glob, Grep, and Read as before.

Process

Step 1: Parse Topic, Scope, and Depth

Parse the user's invocation to determine the research topic and depth.

With topic argument:

/cw-research authentication

The topic authentication scopes exploration to authentication-related files, patterns, and dependencies. Other areas are included only where they intersect with the topic.

Without topic argument:

/cw-research

Perform a general codebase exploration covering all areas without topic filtering.

Depth levels (optional, specified in natural language):

Depth	Behavior	Steps Executed
quick	Auto-explore only — no interactive refinement, no external context, no deep-dive	Steps 1-3, 8-10 (skip 4-7)
medium (default)	Full process as documented	All steps
thorough	Full process + expanded exploration with 2 passes per dimension	All steps, with repeat auto-explore

Examples:

/cw-research quick overview of authentication
/cw-research thorough analysis of the payment system
/cw-research authentication

If the user doesn't mention a depth level, default to medium. Look for keywords like "quick", "brief", "overview" (→ quick) or "thorough", "deep", "comprehensive" (→ thorough) in the invocation text.

Determine topic slug for the output filename:

topic_slug = lowercase, hyphens, no special characters
examples: "authentication" -> "authentication"
          "API rate limiting" -> "api-rate-limiting"
          (no topic) -> "general"

Step 2: Auto-Explore Phase

Launch parallel Task(Explore) subagents to explore the codebase across five research dimensions simultaneously. Each subagent focuses on one dimension and returns structured findings.

Launch all five subagents in a single message for maximum concurrency. Each subagent explores one dimension: Tech Stack & Project Structure, Architecture & Patterns, Dependencies & Integrations, Test & Quality Patterns, and Data Models & API Surface.

Task({
  subagent_type: "Explore",
  description: "Auto-Explore: {dimension name}",
  prompt: "{subagent prompt from references/research-dimensions.md}"
})

See research-dimensions.md for dimension focus areas, subagent prompt templates, and topic filtering examples.

Collecting results: After all five subagents complete, collect their findings into the report template (Step 3).

Step 3: Compile Initial Research Report

Assemble the subagent findings into a structured markdown report. This is the initial version -- it will be enriched with deep-dive findings and external context in later steps.

See report-template.md for the full markdown template and report size guidelines.

The report contains sections for each of the five dimensions (Summary, Tech Stack & Project Structure, Architecture & Patterns, Dependencies & Integrations, Test & Quality Patterns, Data Models & API Surface), with subsections for key findings in each area.

Step 4: Interactive Refinement

Present the auto-explore findings to the user and allow them to confirm, refine, or redirect focus areas before proceeding to deep-dive exploration.

4a. Present findings summary:

Display a concise summary of the auto-explore findings organized by dimension. For each dimension, list the 2-3 most significant discoveries. This gives the user a quick overview before they decide where to focus.

4b. Ask user to confirm, refine, or redirect:

AskUserQuestion({
  questions: [{
    question: "Here are the initial findings from auto-explore. How would you like to proceed?",
    header: "Focus",
    options: [
      { label: "Looks good, continue", description: "Proceed to deep-dive with the current focus areas" },
      { label: "Refine focus areas", description: "Adjust which dimensions get deeper exploration" },
      { label: "Redirect exploration", description: "Shift focus to different areas not covered above" }
    ],
    multiSelect: false
  }]
})

Handle user selection:

• Looks good, continue: Proceed to Step 5 with all five dimensions as deep-dive candidates. The user may still narrow the scope in Step 6 based on which areas are most relevant.
• Refine focus areas: Ask the user which dimensions to prioritize for deep-dive:

  AskUserQuestion({
    questions: [{
      question: "Which areas should receive deeper exploration?",
      header: "Deep Dive",
      options: [
        { label: "Tech Stack & Project Structure", description: "Languages, frameworks, build tools, directory layout" },
        { label: "Architecture & Patterns", description: "Design patterns, module boundaries, abstractions" },
        { label: "Dependencies & Integrations", description: "External deps, APIs, data flow between services" },
        { label: "Test & Quality Patterns", description: "Test frameworks, CI/CD, linting, type checking" },
        { label: "Data Models & API Surface", description: "Schemas, endpoints, request/response shapes" }
      ],
      multiSelect: true
    }]
  })
  

  Use the selected dimensions as deep-dive candidates in Step 6.
• Redirect exploration: Ask the user to describe what they want to explore instead. Use their description to formulate custom deep-dive subagent prompts in Step 6, replacing or supplementing the standard dimensions.

Step 5: External Context Collection

Ask the user if they have external context sources to incorporate into the research. External context enriches the report with information that cannot be discovered through codebase exploration alone.

5a. Prompt for external context sources:

AskUserQuestion({
  questions: [{
    question: "Do you have any external context sources to include in the research? You can provide multiple sources at once. Examples:\n\n- GitHub issues/PRs (e.g., https://github.com/org/repo/issues/42)\n- Jira tickets or project management links\n- Confluence pages or wiki documentation\n- Google Docs or shared documents\n- Local file paths (e.g., ./docs/adr/001-auth-strategy.md)\n- Screenshots or diagrams (image file paths)\n- Web URLs (documentation, blog posts, tutorials)\n- Architecture Decision Records (ADRs)\n- Knowledgebase articles",
    header: "Context",
    options: [
      { label: "Yes, I have sources to add", description: "Provide URLs, file paths, or other references" },
      { label: "No external context needed", description: "Continue with codebase findings only" }
    ],
    multiSelect: false
  }]
})

Handle user selection:

• No external context needed: Skip to Step 6 (Deep-Dive Exploration).
• Yes, I have sources to add: The user provides a list of sources. Accept all sources in a single interaction -- do not require separate prompts for each source.

5b. Classify and process each source:

See external-context-protocol.md for the source classification table, graceful error handling patterns, source attribution rules, and storage format.

Classify each source by type (Web URL, GitHub URL, local file, local directory, image file, or search query) and process with the appropriate tool. Handle inaccessible sources gracefully -- never fail the research process due to an unreachable source.

Step 6: Deep-Dive Exploration

Launch targeted Task(Explore) subagents for deeper exploration of the focus areas identified in Step 4. Deep-dives go beyond the initial auto-explore by investigating specific patterns, tracing data flows, and answering focused questions.

6a. Formulate deep-dive prompts:

For each focus area selected by the user (or all five dimensions if the user confirmed without changes), create a targeted subagent prompt that builds on the initial findings:

Task({
  subagent_type: "Explore",
  description: "Deep-Dive: {dimension name}",
  prompt: "Perform a deep-dive exploration of {dimension name} in this codebase. Initial findings from auto-explore: {summary of initial findings for this dimension}. Go deeper: {specific questions or areas to investigate based on initial findings and user direction}. Topic filter: {topic or 'none'}. Return detailed markdown findings with specific file references, code pattern examples, and actionable insights. Use Glob, Grep, and Read tools. {LSP_INSTRUCTIONS}"
})

Where {LSP_INSTRUCTIONS} is included only when lsp_available = true:

Also use the LSP tool for deeper analysis: use documentSymbol to enumerate symbols in key files, goToDefinition to trace where important types and functions are defined, findReferences to understand usage patterns, goToImplementation to discover interface implementations, and incomingCalls/outgoingCalls to map call hierarchies. LSP provides more precise results than text search for understanding type relationships and call graphs.

6b. Launch subagents concurrently:

Launch all deep-dive subagents in a single message for maximum concurrency, just like the auto-explore phase.

6c. If user redirected exploration (Step 4):

When the user provided custom exploration directions, formulate subagent prompts based on their description rather than the standard dimensions:

Task({
  subagent_type: "Explore",
  description: "Deep-Dive: {user-described focus area}",
  prompt: "Explore this codebase focusing on: {user's description}. Find relevant files, patterns, configurations, and conventions. Return detailed markdown findings with specific file references. Use Glob, Grep, and Read tools. {LSP_INSTRUCTIONS}"
})

Step 7: Update Report with Deep-Dive Findings and External Context

Enrich the initial research report (from Step 3) with deep-dive findings and external context. This step produces the final version of the report.

7a. Integrate deep-dive findings:

For each dimension that received a deep-dive, update the corresponding section in the report. Append deep-dive findings below the initial auto-explore findings, clearly marked:

## {Dimension Name}

{Initial auto-explore findings -- kept as-is}

### Deep-Dive Findings

{Additional findings from deep-dive exploration. Include:
- Specific code patterns with file references
- Detailed data flow analysis
- Edge cases or complexity areas discovered
- Actionable insights for developers working in this area}

7b. Add external context section:

If external context sources were provided in Step 5, add an "External Context" section to the report. See external-context-protocol.md for the report integration format and source attribution rules.

7c. Update the summary:

Revise the Summary section at the top of the report to incorporate key insights from deep-dive findings and external context. The summary should reflect the complete picture, not just the initial auto-explore.

Step 8: Save Report

Save the final enriched report to the output path:

docs/specs/research-{topic_slug}/research-{topic_slug}.md

Create the research directory if it does not exist:

mkdir -p docs/specs/research-{topic_slug}

Write the report file:

Write({ file_path: "docs/specs/research-{topic_slug}/research-{topic_slug}.md", content: "{compiled report}" })

Step 9: Generate Meta-Prompt

After saving the report, generate a "Meta-Prompt" section and append it to the end of the research report. The meta-prompt is a ready-to-use /cw-spec starter prompt enriched with codebase knowledge discovered during research.

9a. Compose the meta-prompt:

See meta-prompt-template.md for the field derivation table and full meta-prompt markdown template.

Derive each field from the research findings (feature name, problem statement, key components, architectural constraints, patterns to follow, suggested demoable units, and code references).

9b. Append the meta-prompt to the report:

Read the saved report file, append the meta-prompt section using the template from meta-prompt-template.md, and write the updated file.

Step 10: Present Results and Next-Step Options

After saving the report with the meta-prompt, present a summary and offer next-step options to the user.

10a. Present the completion summary:

CW-RESEARCH COMPLETE
=====================
Topic: {topic}
Report: docs/specs/research-{topic_slug}/research-{topic_slug}.md
Dimensions explored: 5/5
Deep-dives completed: {N}
External sources incorporated: {N} ({M} inaccessible)

Key findings:
- {finding 1}
- {finding 2}
- {finding 3}

A meta-prompt for /cw-spec has been generated at the end of the report.

10b. Present next-step options:

AskUserQuestion({
  questions: [{
    question: "How would you like to proceed?",
    header: "Next Steps",
    options: [
      { label: "Run /cw-spec with context (Recommended)", description: "Invoke cw-spec with the generated meta-prompt as enriched context" },
      { label: "Review report first", description: "Review and optionally edit the research report before proceeding" },
      { label: "Done for now", description: "Save the report and exit -- you can run /cw-spec later" }
    ],
    multiSelect: false
  }]
})

Handle user selection:

• Run /cw-spec with context (Recommended): Extract the meta-prompt content (everything between the --- markers in the Meta-Prompt section) and invoke cw-spec with it:

  Skill({ skill: "cw-spec", args: "{meta-prompt content}" })
  

  This passes the enriched research context directly into cw-spec, significantly accelerating its Context Assessment step (Step 2).

• Review report first: Display the report path and let the user review or edit the report. After they confirm, re-offer the choice between running cw-spec or exiting:

  The report is saved at: docs/specs/research-{topic_slug}/research-{topic_slug}.md
  
  Review the report and let me know when you are ready to proceed.
  After review, you can run /cw-spec manually with the meta-prompt, or
  re-run /cw-research to regenerate.
  

• Done for now: Confirm the report is saved and exit:

  Report saved: docs/specs/research-{topic_slug}/research-{topic_slug}.md
  
  To use this research later:
  - Run /cw-spec and paste the meta-prompt from the report
  - Or reference the report in your spec prompt for enriched context
  

---

References

Document	Contents
report-template.md	Full markdown report template and size guidelines
research-dimensions.md	Five exploration dimensions with focus areas and subagent prompts
external-context-protocol.md	Source classification, error handling, attribution rules
meta-prompt-template.md	Meta-prompt field derivation and template

---

What Comes Next

After the research report is saved, the typical workflow continues:

1. /cw-spec {feature-name} -- create a specification using the research report as context (the meta-prompt accelerates this)
2. /cw-plan -- transform the spec into a task graph
3. /cw-dispatch -- execute tasks in parallel

The research report at docs/specs/research-{topic_slug}/research-{topic_slug}.md serves as enriched context that accelerates cw-spec's Context Assessment step (Step 2), producing more detailed and accurate specifications.