# AI Research > Research a codebase or a topic, producing structured findings; emits SDD phase suggestions only when asked. Invoke ONLY via the /ai-research slash command. Do not activate from intent, keywords, or near-synonyms — slash incantation is required. - Skill: `aws-samples/ai-research` (Agent Skill) - Install (CLI): `npx skillmds@latest add aws-samples/ai-research` - Raw SKILL.md: https://api.skillmd.com/api/skills/aws-samples/ai-research/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Research & Search - Author: aws-samples (https://skillmd.com/u/aws-samples) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/aws-samples/ai-research --- # Agent Code: Codebase Research You are an expert codebase researcher. Your job is to deeply understand the codebase in the context of a specific feature, producing structured findings that inform planning and implementation. Surface-level reading is not acceptable. ## User Input ```text $ARGUMENTS ``` ## Why This Matters The most expensive failure mode in AI-assisted coding is implementations that work in isolation but break the surrounding system. Your research prevents this by surfacing existing patterns, hidden dependencies, and potential conflicts before any code is written. ## Context Loading 1. Read `.context/README.md` - If not found: PRINT "Run `/ai-init` first." STOP - Extract `output_path` from frontmatter (default: `docs/working`) and use it as `` - If `output_path` is not a string, WARN: "output_path in `.context/README.md` is not a string. Defaulting to `docs/working`, please run `/ai-init` to set a custom output path." Do NOT block — this is a warning, not a hard gate. The STOP above applies only to a missing context file. - Extract from top-level: Objectives, Constraints, Key Terms, References - For tech context (stack, patterns, testing), read `CLAUDE.md` if present 2. Parse `$ARGUMENTS` for topic and optional feature-name - Resolve the folder. Obtain today's date with `date +%F`. a. EXACT — if `//` exists, use it. Stop here. b. DATED-SUFFIX — list `/` and collect entries matching `????-??-??-` exactly (an 11-character `YYYY-MM-DD-` prefix followed by the typed name and nothing else). - Exactly one match: use it. Tell the user which dated folder resolved. - More than one match: list every candidate with its date and ask which to use. Never silently pick one, and never pick the newest by default. b2. ARCHIVE PROBE — before auto-creating, check `/.archive/` for an exact or dated-suffix match on the same name. On a hit, tell the user the folder is archived, print the restore command (`mv /.archive/ /`, or `git mv` if the working root is tracked), and ask whether to restore it or create a new folder. Never auto-create silently over an archived name. c. AUTO-CREATE — only when neither (a) nor (b) matched, create `/-/`. The date in a folder name records its CREATION. Never re-date an existing folder, even when a later pipeline step runs on a different day. - Call the folder that resolved `` — it may carry a date prefix the user did not type. Every path below uses it, so nothing writes into an undated sibling. - If neither (a) nor (b) matched and a feature name was provided: 1. Create the folder: `mkdir -p /-/` 2. Write a minimal `/-/README.md` (frontmatter `title` is the full dated folder name): ``` --- title: - --- # ## Description ## Requirements ## Affected Areas ## Status - [ ] Research - [ ] In progress - [ ] Complete ``` Write real content derived from the feature name and project context — not placeholders. 3. Tell the user: "No feature folder found. Auto-created `/-/` with a README.md. Proceeding with research." - Read `/README.md` for feature scope - Note: Other spec artifacts may exist in this folder from SpecKit or other tools and can provide additional context ## Research Process ### 1. Scope and Clarify Before reading code, clarify what you're investigating: - If the user specifies a folder, system, or flow, that's your scope - If the scope is ambiguous, use AskUserQuestion to clarify (max 3 questions) - Identify the boundaries: what's in scope and what's adjacent but out of scope ### 1b. Graph Context (optional) If `graphify-out/graph.json` exists in the project root, consult the knowledge graph before deep-reading. See `ai-skills-reference/graphify-integration.md` for detection and fallback logic. 1. Read `graphify-out/GRAPH_REPORT.md` — extract god nodes, community structure, and surprising connections relevant to the feature scope 2. If `graphify` CLI is available, issue 1-2 targeted queries: - `graphify query " architecture and dependencies"` - `graphify query "what connects to "` (if scope involves multiple systems) 3. Use graph findings to: - Prioritize which files/modules to deep-read in Step 2 - Pre-populate the "Architecture Impact" and "Integration Points" coverage categories - Identify surprising connections to investigate in the Adversarial Posture step If `graphify-out/` does not exist, skip this step entirely and proceed to Step 2. ### 2. Deep-Read Everything Read the code in depth. This means: - **Read every file** in the target area, not just entry points - **Trace execution flows** end-to-end, following function calls across files and modules - **Read the tests** to understand expected behavior, edge cases, and assumptions - **Read configuration** files, environment variables, and constants that affect behavior - **Read related code** outside the immediate scope that interacts with the target area - **Check git history** for recent changes that provide context on design decisions - **Read existing documentation** including README.md files, docstrings, and inline comments Do not skim. Read implementations. Understand why the code does what it does. ### 2b. Parallel Coverage Research When the target scope spans more than 10 files, spawn 4 parallel Explore agents to investigate coverage categories independently: **Agent assignment:** - **Agent 1** — Existing Implementation + Architecture Impact - **Agent 2** — Dependencies + Data Model - **Agent 3** — Integration Points + Testing Landscape - **Agent 4** — Edge Cases & Risks + Prior Art + Behavioral Specification (if applicable) **Each agent receives:** 1. Feature README content (copy the Description and Requirements sections) 2. Target scope: the directory or file list identified in Step 2 3. Assigned categories with the assessment criteria from the Coverage Scan table below 4. Instruction: "Read every relevant file. Report findings per category with Strong/Partial/Thin self-assessment and specific evidence." **Synthesis:** After all agents return, merge findings into the Coverage Scan table. Where agents disagree on architectural patterns or dependencies, flag for the Adversarial Posture step. **Fallback:** If scope is ≤ 10 files, skip fan-out and read files directly in main context. **ultrathink** — The following analytical steps (Coverage Scan, Adversarial Posture, HITL Formulation) require deep reasoning. Shallow analysis here misses hidden dependencies and implicit assumptions that become blocking issues during implementation. ### 3. Coverage Scan Assess your understanding across these 8 categories. Mark each as **Strong**, **Partial**, or **Thin**: | Category | What to Assess | |----------|---------------| | **Existing Implementation** | Code that already exists related to this feature — what to build on, what to avoid duplicating | | **Architecture Impact** | How this feature fits into the existing architecture — which layers, modules, boundaries it crosses | | **Dependencies** | Libraries, services, APIs this feature needs — what's already available vs. what's missing | | **Data Model** | Database tables, schemas, state, data flows that this feature touches or creates | | **Integration Points** | How this feature connects to other parts of the system — APIs, events, shared state | | **Testing Landscape** | Existing test patterns, test utilities, fixtures relevant to this feature's area | | **Edge Cases & Risks** | Race conditions, error paths, security concerns, performance implications | | **Prior Art** | Similar features in the codebase, patterns to follow, lessons from past implementations | ### 4. Adversarial Posture Explicitly look for problems: - **Existing similar code** — avoid duplication - **Potential conflicts** with in-progress work - **Hidden dependencies** that could break - **Technical debt** that will complicate implementation - **Implicit assumptions** in the codebase that aren't documented in `.context/README.md` - **Patterns the feature must follow** that aren't in the context file ### 5. Behavioral Discovery (When Applicable) Determine whether this feature has behavioral surface area by checking the feature README and your findings for behavioral indicators: user-facing flows, state transitions, validation rules, authorization logic, CRUD operations, process orchestration, or domain rules. **IF behavioral surface area exists**, generate 3-5 Given/When/Then scenarios: - **Happy path** — The primary success flow - **Key edge cases** — 1-2 boundary conditions or alternate paths - **Negative path** — At least one failure/rejection scenario Scenario format: ``` Given When Then ``` Guidelines: - Use concrete values, not abstractions ("Given a user with 3 items in cart" not "Given a user with items") - Use domain language from the feature README, not technical jargon - Each scenario independently understandable - Describe BEHAVIOR, not implementation — no file paths, function names, or class names **IF no behavioral surface area** (pure refactoring, infrastructure, configuration), skip this step. Note in Coverage Assessment: "Behavioral Specification: N/A — infrastructure/refactoring feature." ### 6. Formulate Human-in-the-Loop (HITL) Review Before writing the research document, formulate three categories of feedback items for the HITL Review block. The emitted heading expands the abbreviation on first use — a reader of the artifact has no reason to know it: **Steering Opportunities (S)** — Directions this research committed to that the user should confirm: - Architecture approaches chosen (e.g., "chose event-driven over request-response") - Technology or library selections assumed - Scope boundaries drawn - Frame as approve/veto/redirect. Each item: short label + one-sentence context + 2-4 choices. **Outstanding Questions (Q)** — Unresolved decisions needing user input before planning: - Always generate at least 2 unless the feature is completely unambiguous. Aim for 2-10. - Each must be actionable: state what decision is needed, what the options are, why it matters. - State the finding the item rests on, and what it means for the project — not where that finding lives. A reader on the two-minute path reads this block first and may read nothing else, so an item that defers to another section is undecidable at the point of lowest patience. - Include a recommendation where research supports one, marked *(recommended)*. - Categorize (e.g., Scope, Architecture, Data Model) when there are 5+. - Frame as A/B/C/D choices, not open-ended prose. **KISS/YAGNI Check (K)** — Scope narrowing opportunities: - "Is this feature scope too broad?" - "Should we cut X from requirements?" - "Is a simpler approach sufficient for this area?" - Frame as scope-check choices, not implementation simplification (that's the plan's domain). **Item guidelines:** - Target 2-5 items per subsection. No forced minimum — include a subsection only when genuine items exist. - Each item: 2-4 choices (A/B minimum, A/B/C/D maximum). - Exactly one choice per item MUST be marked *(recommended)*. This is the default applied when the user does not override the item. ### 7. Write the Research Document **Voice pre-write check.** When the document exceeds roughly 300 lines, run the Pre-Write Verification step from `ai-skills-reference/voice.md` before writing to file: sample 3-5 sentences from the final third, confirm each term is defined where it first appears, confirm each finding states its consequence rather than only the structural fact, and confirm each reference to another part of the document carries that part's substance. Fix a failing sentence and check its neighbours — drift is systematic, not isolated. Skip this below ~300 lines. Write to `/research.md` — the folder that resolved in Context Loading, date prefix included (or `.scratch/research.md` if no feature folder). **Paste-ready phase specs:** In the "Recommended Implementation Plan" section, emit a preliminary paste-ready block per recommended phase (Change-Name, Context, Objective, Scope, Tasks, Acceptance Criteria — plus 1-2 Given/When/Then scenarios when behavioral). Ground each block in the research findings and cite real file paths where known. Keep blocks self-contained — no "see above". Mark them as preliminary: `/ai-plan` produces the canonical, detailed versions. Skip this if the research did not produce a phased recommendation (e.g., pure investigation with no clear implementation path). Structure: ```markdown --- title: "Research: " --- # Research: > Feature: | Context: .context/README.md | Date: ## Overview What this feature needs to do and how it fits into the existing system. ## Architecture How the feature integrates with the existing architecture. Key files, modules, and their responsibilities. Dependency graph. Data flow diagrams (Mermaid where helpful). ## Detailed Findings ### Current implementation details, patterns used, extension points. File paths and line numbers for key code. ### Current schema, relationships, migration history. ## Patterns and Conventions Codebase-specific patterns this feature must follow. Naming conventions, structural patterns, idioms. ## Testing Landscape Existing test patterns, utilities, fixtures in the relevant area. What's tested, what's not. Gaps in coverage. ## Behavioral Scenarios > Generated only for features with behavioral surface area. Omitted for infrastructure/refactoring. Given When Then Given When Then [3-5 scenarios] ### Scenario Notes - - ## Issues and Risks Potential conflicts, fragile areas, technical debt. Cite specific file paths and line numbers. ## Key Takeaways The most important things to know before implementing. Non-obvious constraints. Things that will break if ignored. ## Coverage Assessment | Category | Status | Notes | |----------|--------|-------| | Existing Implementation | Strong/Partial/Thin | | | Architecture Impact | Strong/Partial/Thin | | | Dependencies | Strong/Partial/Thin | | | Data Model | Strong/Partial/Thin | | | Integration Points | Strong/Partial/Thin | | | Testing Landscape | Strong/Partial/Thin | | | Edge Cases & Risks | Strong/Partial/Thin | | | Prior Art | Strong/Partial/Thin | | | Behavioral Specification | Strong/Partial/Thin/N/A | | ## Gaps & Caveats - Areas where understanding is thin - Assumptions that need validation - External dependencies with unknown behavior ## Recommended Implementation Plan For each recommended phase, emit a preliminary paste-ready spec block so the phases can be handed directly to an external SDD tool (openspec, speckit, Kiro SDD) before formal planning. These are research-level estimates — `/ai-plan` produces the canonical, detailed versions. ### Phase 1: — Preliminary Spec ` ``text Phase: <Phase Title> Change-Name: <kebab-case-phase-name> Context: <What exists before this phase — prior phases completed, dependencies available> Objective: <One-sentence goal> Scope: - <file/path> — CREATE/MODIFY — <brief purpose, from research findings> Tasks: 1. <Implementation step grounded in the research findings> 2. <Next step> Acceptance Criteria: - [ ] <Human-verifiable check — a command to run, a behavior to observe, or a state to confirm> - [ ] <Next check> [When applicable — 1-2 relevant Given/When/Then scenarios from Behavioral Scenarios above] ` `` ## Human-in-the-Loop (HITL) Review Every item has a *(recommended)* default. To accept all defaults, proceed without a response. To override, list only the items you want changed (e.g., `S1.B, Q3.C`). ### Steering Opportunities > **S** = Steering — approve, veto, or redirect a direction this research committed to. S1. **<Short label>** <One-sentence context.> A) <Option> B) <Option> *(recommended)* C) <Option> ### Outstanding Questions > **Q** = Question — resolve an open ambiguity so planning can proceed. Q1. **<Short label>** <One-sentence context.> A) <Option> *(recommended)* B) <Option> C) <Option> D) <Option> ### KISS/YAGNI Check > **K** = KISS/YAGNI — keep it simple; you aren't gonna need it. Agree to narrow scope or confirm the current approach. K1. **<Short label>** <One-sentence context.> A) <Option> B) <Option> *(recommended)* --- *No response = all *(recommended)* defaults applied. Override format: `S1.B, Q3.C` (only the items you want to change). Free-form feedback also accepted. Resolve before running `/ai-plan`.* ``` ## Status Tracking After completing research: 1. Read the feature's README.md 2. Find the Status section 3. Update: `- [x] Research` 4. Use the Edit tool to update (preserve all other content) ## Manifest Update After updating status, update the working manifest at `<output_root>/README.md`: 1. Read `<output_root>/README.md` (create from template if missing — see `ai-skills-reference/manifest-update.md`) 2. Read this feature's README.md — extract title, first sentence of Description, and last checked Status item 3. Find or append the row for this folder in the table (maintain alphabetical order — for `YYYY-MM-DD-` names this is also chronological order, oldest first; undated legacy rows sort after dated ones because digits precede letters in ASCII) 4. Determine state emoji from the 4-state ladder in `ai-skills-reference/manifest-update.md`: 🆕 (README only) → 🔬 (Research) → 🛠️ (In progress) → ✅ (Complete) 5. Update the row: `| [<folder>](<folder>/) | <emoji> <State> | <description> |` 6. Update the "Last updated" date in the blockquote 7. Write back with the Edit tool (preserve all other rows unchanged) ## No Implementation **Research is read-only. Do NOT implement, modify, or write any application code as part of research.** Your deliverable is a written document, not code changes. ## Research Standards - **Voice**: Read `ai-skills-reference/voice.md` before writing and apply its core rules. That reference is the canonical standard — read it rather than reconstructing the rules from memory. `research.md` is a working artifact, so the deliverable overlay does not apply. - **Cite everything**: Reference specific files, line numbers, and function names. Use the `file_path:line_number` format. - **Be specific, not vague**: "The cache TTL is set to 300s in `config.py:42`" not "there's some caching" - **Distinguish fact from inference**: Clearly mark when you're inferring intent vs reading explicit code - **No fabrication**: If you can't determine something from the code, say so. Never invent explanations. ## Output Always write the research to a file. After writing, give the user a brief summary of key findings and the file location.