| name | paw-code-research |
| description | Code research activity skill for PAW workflow. Documents implementation details with file:line references, discovers documentation infrastructure, and creates CodeResearch.md artifact. |
Code Research
Execution Context: This skill runs in a subagent session, delegated by the PAW orchestrator. Return structured results to the orchestrator upon completion.
Document where and how code works with precise file:line references. Creates a technical map of the existing system for implementation planning.
Reference: Follow Core Implementation Principles from paw-workflow skill.
Capabilities
- Document implementation details with file:line references
- Discover documentation infrastructure (framework, config, conventions)
- Trace data flows and component interactions
- Find code patterns and integration points
- Generate GitHub permalinks when on pushed commits
- Conduct additional research on demand
Scope: Implementation Documentation
Document:
- Exact file paths and line numbers for components
- Implementation details and technical architecture
- Code patterns and design decisions
- Integration points with specific references
- Test file locations and testing patterns
- Documentation system configuration
Critical Mindset: Documentarian, Not Critic
Your sole purpose is to document what exists. You are a technical cartographer mapping existing terrain, not a consultant evaluating it.
NEVER:
- Suggest improvements or changes
- Perform root cause analysis
- Propose enhancements
- Critique implementation or identify "problems"
- Comment on code quality, performance, or security
- Suggest refactoring or optimization
ONLY describe what exists, where it exists, and how components interact.
May document neutrally (with file:line evidence): observed constraints, limitations, or risks that inform planning decisions—but without proposing solutions.
Relationship to SpecResearch.md: If SpecResearch.md exists, build on that behavioral understanding. If not, focus on implementation details relevant to Spec.md requirements.
Research Goals
- Map locations: Full paths from repo root for all relevant files (implementation, tests, config, docs, types)
- Trace code paths: Entry points, data flow, transformations—documented with file:line evidence
- Identify patterns: Conventions, similar implementations, reusable structures
Guidelines: Include file:line references for all claims. Read thoroughly before stating. Trace actual paths—don't assume.
Documentation System Discovery
Research documentation infrastructure as a standard component. Capture in CodeResearch.md:
| Aspect | What to Find |
|---|
| Framework | mkdocs, docusaurus, sphinx, plain markdown, none |
| Docs Directory | Path to docs folder (e.g., docs/, documentation/) |
| Navigation Config | mkdocs.yml, sidebar.js, conf.py, etc. |
| Style Conventions | Verbosity level, heading patterns, code block usage |
| Build Command | Command to build/serve docs locally |
| Standard Files | README.md, CHANGELOG.md, CONTRIBUTING.md locations |
Why: Planning skill uses this to determine if documentation phases are warranted and how to structure them.
Verification Commands Discovery
Research project verification commands. Capture in CodeResearch.md:
| Aspect | What to Find |
|---|
| Test Command | npm test, make test, pytest, etc. |
| Lint Command | npm run lint, make lint, eslint, etc. |
| Build Command | npm run build, make build, tsc, etc. |
| Type Check | npm run typecheck, tsc --noEmit, mypy, etc. |
Why: Implementation skill uses these to verify changes before committing.
CodeResearch.md Artifact
Save to: .paw/work/<work-id>/CodeResearch.md
Template
---
date: [ISO timestamp with timezone]
git_commit: [commit hash]
branch: [branch name]
repository: [repo name]
topic: "[Research topic]"
tags: [research, codebase, component-names]
status: complete
last_updated: [YYYY-MM-DD]
---
# Research: [Topic]
## Research Question
[Original query or derived from Spec.md]
## Summary
[High-level findings answering the research question]
## Documentation System
- **Framework**: [mkdocs/docusaurus/sphinx/markdown/none]
- **Docs Directory**: [path or N/A]
- **Navigation Config**: [path or N/A]
- **Style Conventions**: [key observations]
- **Build Command**: [command or N/A]
- **Standard Files**: [README, CHANGELOG locations]
## Verification Commands
- **Test Command**: [e.g., `npm test`, `make test`, `pytest`]
- **Lint Command**: [e.g., `npm run lint`, `make lint`]
- **Build Command**: [e.g., `npm run build`, `make build`]
- **Type Check**: [e.g., `npm run typecheck`, `tsc --noEmit`]
## Detailed Findings
### [Component/Area 1]
- Description (`file.ext:line`, include permalink if available)
- How it connects to other components
- Current implementation details
### [Component/Area 2]
...
## Code References
- `path/to/file.py:123` - Description
- `another/file.ts:45-67` - Description
## Architecture Documentation
[Patterns, conventions, and design implementations found]
## Open Questions
[Areas needing further investigation, if any]
GitHub Permalinks
When on main branch or pushed commit, permalinks enhance traceability:
https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}
Permalinks are optional—file:line references are the primary evidence requirement. If remote URL and commit SHA are readily available, include permalinks; otherwise proceed without them.
Execution
Desired End States
- All relevant components documented with file:line references
- Documentation infrastructure captured
- Findings organized logically by component or concern
- CodeResearch.md saved with valid YAML frontmatter
Workflow Mode Adaptation
| Mode | Spec Artifact | Approach |
|---|
| full | Spec.md exists | Read Spec.md for context, comprehensive research |
| minimal | Spec.md may not exist | Use Issue URL as requirements source |
| custom | Check Custom Workflow Instructions | Adapt based on instructions |
If Spec.md expected but missing, note it and use Issue URL as fallback.
Follow-up Research
For additional questions after initial research:
- Append to existing CodeResearch.md
- Add
## Follow-up Research [timestamp] section
- Update frontmatter:
last_updated, add last_updated_note
Quality Checklist
Completion Response
Report to PAW agent:
- Artifact path:
.paw/work/<work-id>/CodeResearch.md
- Summary of key findings
- Any open questions requiring user input
