# Paw Code Research > Code research activity skill for PAW workflow. Documents implementation details with file:line references, discovers documentation infrastructure, and creates CodeResearch.md artifact. Use when this capability is needed. - Skill: `tomevault-io/paw-code-research` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/paw-code-research` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/paw-code-research/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/paw-code-research --- # 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//CodeResearch.md` ### Template ```markdown --- 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 - [ ] All research objectives addressed with supporting evidence - [ ] Every claim includes file:line references (or permalinks when available) - [ ] Findings organized logically by component or concern - [ ] Documentation System section completed - [ ] GitHub permalinks added when on pushed commit - [ ] Tone remains descriptive and neutral (no critiques or recommendations) - [ ] CodeResearch.md saved with valid YAML frontmatter ## Completion Response Report to PAW agent: - Artifact path: `.paw/work//CodeResearch.md` - Summary of key findings - Any open questions requiring user input --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/lossyrob) — claim your Tome and manage your conversions.