research-codebase
Document how the codebase works today for an issue or question, written by a ticket-blind subagent into docs/research/.
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- research-codebase
- description
- Document how the codebase works today for an issue or question, written by a ticket-blind subagent into docs/research/.
- argument-hint
- Issue number, or a question about the codebase
- disable-model-invocation
- true
03 SKILL.md 正文
<!-- Adapted from humanlayer/humanlayer@99abe67 .claude/commands/research_codebase.md, Apache-2.0. Modified for dk-agent-kit: split into a ticket-blind question step and a single documentarian subagent (idea from humanlayer/humanlayer-pi@f4bd3ed create-research-questions), output to tracked docs/research/, GitHub issues instead of Linear/thoughts/, diagrams drawn by dk:pr's Diagram rules. -->
Produce a research document that describes the codebase as it exists today: what exists, where, and how it connects. The writer is a documentarian — a technical writer mapping existing territory — and stays ticket-blind: it sees neutral research questions, never the issue, so the planned change cannot bend what it reports.
1. Write the research questions (this session)
-
Work in the issue's worktree (the
dk:issue-flowskill), so the document lands on the issue's branch. Read the input. For an issue number, rungh issue view <N> --json title,body,labels,comments. Otherwise the argument is the user's question. -
Write 2–8 research questions about how the codebase works today. Each one asks "how does it work", in the shape of: "Trace the flow from
<entry point>to<data store>", "How do<A>and<B>exchange data, on both sides?", "Where is<table/column/config key>read and written?". Phrase them neutrally, so a reader of the questions alone could not guess the planned change or a solution. When the issue touches UI, add a question about the existing component library and styling conventions. -
Compute the output path:
docs/research/YYYY-MM-DD-<issue>-<slug>.md(drop<issue>-when there is none), where<slug>is a 2–4 word kebab-case name for the researched area, also neutral. -
Run
git check-ignore -q <output path>. Exit status 0 means the path is ignored: stop and tell the user the repo needs a.gitignoreexception fordocs/research/. -
Save the questions file to your session scratchpad directory (from the system prompt;
mktemp -dif none is listed) asresearch-questions.md:--- output: docs/research/2026-01-08-42-session-storage.md issue: 42 # or "none" --- # Research questions 1. ... ## Key context pointers - Paths, packages, and links named in the input, verbatim. Omit the section if there are none.
Done when the questions file exists, every question is descriptive, and the output path is confirmed tracked.
2. Dispatch the documentarian (one subagent)
Dispatch ONE general-purpose subagent in the foreground. Its prompt is the brief below with two absolute paths filled in: the questions file, and the dk:pr skill's file (../pr/SKILL.md from this skill's base directory). Pass nothing else from the issue or this conversation.
You are a documentarian. Your whole brief is
<questions file path>: read it, answer every research question, and write one Markdown document to theoutputpath it names (relative to the repo root).Describe what exists, where it lives, and how the parts connect, citing
file:line(orfile:start-end) for every claim. Your reader wants a map of the territory as it stands; write every sentence as description of current behaviour. Draw each diagram by the Diagram rules in thedk:prskill, read from<pr skill file path>.Fan out in parallel with the Agent tool, grouping related questions into 2–6 well-scoped prompts:
dk:codebase-locatorfinds where things live,dk:codebase-analyzertraces how specific code works,dk:codebase-pattern-findershows existing examples and tests. Start with locators, then send analyzers at the most promising findings. Wait for all of them, then verify any surprising claim by reading the cited lines yourself. If the Agent tool is unavailable to you, do the same work directly with Grep, Glob and Read.Gather
date(date +%Y-%m-%d),git_commit(git rev-parse --short HEAD) andbranch(git branch --show-current), then write:--- date: <YYYY-MM-DD> git_commit: <short sha> branch: <branch> issue: <from the questions file> questions: - <each research question, verbatim> --- # Research: <area> ## Summary <a few paragraphs: how the researched area works today> ## Detailed findings ### <one section per question; the heading states the answer as a takeaway> <prose with inline file:line citations; tables, Mermaid, call trees or file trees where they show structure faster than prose; how this area is tested today, or that it has no tests> ## Code references - `path/to/file.ext:12-40` — what is there (group by area; say whether a group is exhaustive) ## Open questions - <each question, or part of one, you could not answer from the code, and what you checked>Done when every research question has an answer with
file:linereferences or appears under Open questions. Reply with the document path and the number of open questions.
3. Check and report (this session)
- Read the document against the issue or question. Rewrite any sentence that judges, recommends, proposes, or rates — anything that reads as an opinion or a solution — into neutral description of what the code does, or delete it.
- Check the completion criterion yourself: every research question has an answer with
file:linereferences, or is listed under Open questions. Send the subagent back (SendMessage) for any question that has neither. - When an issue was given, comment on it with
gh issue comment <N> --body "<one line>: <link>", where the link ishttps://github.com/<owner>/<repo>/blob/<branch>/<output path>(fromgh repo view --json owner,name); note in the comment that it resolves once the branch is pushed. - Tell the user the document path, a two-line summary, the open questions, and that the document is uncommitted and ready to commit.
04 同仓库更多 Skills
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
verify
Prove a change works by driving it in a stack you started, against a control run of the pre-fix state. Use before calling any change verified, or when asked to verify or prove a fix.
verify-doc-check
Monthly check that this repo's docs/agents/verify.md still starts the stack: read every claim against the source, run the recipe in a fresh worktree, fix or file each drifted step.
triage
Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
to-tickets
Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker (edges as text in one file per ticket locally, or native blocking links on a real tracker).
to-spec
Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed.