Skip to content

m3taz-ahmed/aizee / skills/bmad-deep-recon

bmad-deep-recon

Verified

Decision-grade research on a topic or this repository. Use when the user says "deep recon", "research this", "draft a research prompt", "process this research report", "market research", "domain research", "technical research", "competitor research", "what users say about X", "literature review", "help me choose between", "research the codebase", "research how X works here" or "why is X built this way". Not for a quick code question answered in chat.

references/codebase.md

View on GitHub
# Codebase

One ask about a repository, whether a question, a ticket or a goal, becomes a short document that says how the relevant code works at one commit and how it got that way, every claim cited to a line or a commit, with no recommendation in it. Its readers are the plan step that will change the code and a person checking one claim; what to change is theirs to decide.

The user's intent stays with you. With the user you turn the ask into factual questions; subagents answer them from the code and its history knowing only the questions, because a researcher who knows what is being built reports what should be instead of what is. You read the ask, the layout, the digests and script output; they read the code.

## Questions

Four shapes: `how does X work`, `why is X this way`, `where does X live`, `what touches X`. Locators (search only, one per area of the repository's layout, run first over all the questions) find where the code lives; an analyzer answers each question from it; a historian follows a `why` question's cited lines through git history, and dates two patterns an analyzer found doing the same thing, nothing else; verifiers re-check claims. Each role's brief is `references/codebase-<role>.md`.

Write questions that send researchers to every part of the code the ask depends on, none stating the intent or naming what the ask wants built: "how does a job run end?", not "where would cancellation go?" or "can a running job be cancelled?". An ask from a ticket or goal also gets a question on how that code is tested. A question fits one analyzer within `{workflow.codebase_file_budget}` files; the set fits one short document. An ask with no such set ("document the whole project") gets a short list of bounded asks instead and no run; headless, end `blocked` with them in `open_questions`. An ask one file answers gets its answer in chat, cited, and a run only if the user still wants the document; headless, run as asked.

**The plan gate** is the one hard stop before research: the questions with their shapes; the repository and commit, which the research reads alone, so a dirty tree is invisible to it; the budgets and `{workflow.validation}`, which the `bmad-customize` skill changes for this repository (offer `npx skills add bmad-code-org/BMAD-METHOD --skill bmad-customize` when it is not installed); and the prior document a follow-up opens. An edit goes back through the rules above, since a question the user adds can state the goal as easily as one you draft. Headless, proceed with the set as drafted.

## The run

Before the gate: the repository is the session's git top level unless the ask names another; record its full and short commit and its branch. A ticket ref resolves with `uv run {project-root}/_bmad/method/scripts/tickets.py --project-root {project-root} find <ref>`. List by title the run folders under `{workflow.research_output_path}` and the repository's decision records (ADRs: `adr-*.md`, or a decisions folder), and open one only when the ask names or continues it, since a document in context gets repeated whether or not it still holds.

After the gate, bind the run. The folder is `uv run {skill-root}/scripts/recon_kit.py slug "<subject>" --type codebase --pattern "{workflow.run_folder_pattern}"` under `{workflow.research_output_path}`, `<subject>` a neutral few words for the set (`job runner lifecycle`), never the ask, since the name shows in paths; an existing folder gets `-{date}` in the pattern unless it holds this subject's unfinished run, which you resume. `brief.md` is all a researcher learns: the numbered questions with their shapes, the full and short commit, the budgets, the validation level, and the paths left out of every search, relative to the repository (`{output_folder}`, `_bmad/`, `{workflow.research_output_path}`, and any other folder of plans, specs, stories or tickets inside it, since they state the intent); the repository path only when it is not the working directory, because a worktree's folder often carries the task's name. Init the memlog (`uv run {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field type=codebase --field repository=<path> --field commit=<sha>`), log the ask and the set as `decision` lines (an `assumption` when headless), seed `<folder name>.md` from `{skill-root}/assets/codebase.template.md`, and tell the user the path.

Spawn every subagent fresh and directly, never through a workflow, which relays the triggering request to every agent it runs, and as a subagent type without the project's instruction files and git status when the harness has one, since those can name the work in progress. One message, with nothing from the ask: read `{skill-root}/references/codebase-<role>.md`; the text of `brief.md` (only its own question for an analyzer, historian or verifier); the assignment, an area or paths, symbols and ledger lines copied from the digests and the ledger; reply with the digest. No second message: what a subagent could not settle goes in its digest. The run folder's path stays out of every prompt, and each reply is written to `{doc_workspace}/digests/<role>-<question or area>[-<n>].md` as it arrives, so a run resumes from disk. `{workflow.subagents}` caps how many run at once (`low` 2, `normal` 3, also when empty, `high` 6); when `{workflow.subagent_models}` is set, analyzers and historians take its first available entry, locators and verifiers its last, at the lowest reasoning effort the harness offers, since their work is search and comparison. With no subagents, take each role yourself from its file, and say under the document's questions that the firewall was not in force.

Areas come from the layout (`git ls-tree` at the top one or two levels, top-level files as one area, excluded paths left out), not from the ask, so the area list does not hint at the change in mind. When a question's budget runs out, or an answer opens a question the set does not hold, that question stops: write what its digests hold, and put where it stopped and the next ask, drafted by the rules above, in `## Open questions`.

## The document

Write each question's section as its digests land, from them alone and in their words, each claim with its citation as the digest gave it (code `path:line (symbol) @ sha`, history `sha "subject" #pr`); a `what touches X` section keeps every call site its digest cites, each with its citation, since the list is the answer. Log a memlog `claim` line, `ref=[n] status=unverified kind=<code|history> — <the claim's sentence as the document has it, with its citation>`, for each claim the level verifies: at `normal` the few the analyzers and historians marked load-bearing and every claim of a question no analyzer took; at `high` and `max` all; `n` is one integer per claim across the run, which is how `tally` reads the ledger. Then `uv run {skill-root}/scripts/recon_kit.py anchors {doc_workspace}/<folder name>.md --repo <repository> --at <commit>` re-finds every citation; a claim it fails, or reports with `symbol_found` false, gets a ledger line whatever the level. Verifiers take the question's ledger lines; each verdict is a new `claim` line with the same `ref=`, `--by verifier`. Correct an `overturned` or `disputed` claim to what the verifier found, the original noted in words without its old citation; mark an `unverified` one where it stands. A question is done when `anchors` exits 0 and each of its refs has a verifier's line.

`## Where the answers meet`, after the question sections and only when two answers pass through the same method: each such method, the questions whose answers reach it, and the checks there that reject a value or throw, every line a claim the question sections already cite, with that citation. It states what the code shares, never what to change.

`## Decisions found`, last and only when there is one, proposes a decision record (ADR) for each decision the historians found in a commit or pull request that no listed ADR covers and that is hard to reverse, surprising without context and the result of a real trade-off, each shown from the history, never the ask, and cited as the verified section cites it. Verify proposals like any claim, then ask the user about each, interactively only, and record the answer beside the proposal. An approved one is `adr-<decision-slug>.md`, a title stating the decision and one paragraph (context, decision, why, naming the commit) drawn from the history alone, beside the code it governs or, system-wide, in the repository's decisions folder, else `docs/decisions/`; committing it is the user's concern. Log each answer as a `decision`.

To close: apply `{workflow.doc_standards}` to the prose, each pass told the readers and bar this file opens with and that the sections and every citation stay, never folded into an uncited summary; rerun `anchors` until it exits 0; set `status: complete`, `updated` and `claims` from `uv run {skill-root}/scripts/recon_kit.py tally {doc_workspace}/.memlog.md`; log a closing `event`; when the ask came from a ticket file that exists (find's `story_file`, or the file the user named), append `- research — <document path>, <section>` to its References. Then `references/finalize.md` for rendering, handoffs, the closing report and `{workflow.on_complete}`: its synthesis, citation and polish steps are done; a briefing shows the frontmatter as header and the document's sections, marking only what the document marks; and in place of a staleness map the closing report says that `anchors` run later without `--at` shows which cited files changed since the commit.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall