arjunrajlaboratory/mycelium/review

Mycelium — Review

Resolve bundled skills/ paths relative to the Mycelium plugin root (two directories above this SKILL.md). Resolve repository and .living/ paths relative to the user's working repository.

Review code, analysis, or documentation changes for the kinds of mistakes that matter in scientific data work. Two modes plus one opt-in follow-up:

• Default: dispatch six specialized sub-agents, parallelized up to the

host capacity and run in waves when necessary, then synthesize a single prioritized report.

• `grill`: walk the user through every consequential analytical decision

conversationally, one question at a time.

• Tripwires (opt-in, offered after default): perturb inputs and verify

the pipeline actually fails at named scientific boundaries. Three categories — fault-injection, metamorphic, and known-answer tests. Three modes — audit (default: write a behavioral spec describing which tripwires would apply, no code runs), scaffold (propose project-specific patches that add the instrumentation hooks), run (execute against existing instrumentation). Scaffold and run are agent-improvised per analysis rather than template-stamped. See skills/core/references/review/deep-tripwires.md.

The point of progressive disclosure is that the main skill stays under your context budget and only loads the per-domain checklists into the sub-agents that need them. Don't read the per-agent checklists yourself unless you are debugging the skill — pass the file paths to the sub-agents.

Why this skill exists

LLM coding agents tend to make the same kinds of mistakes when generating analysis code, and many are silent: code that runs cleanly and produces a confidently wrong number. This skill encodes the catalog of those failure modes, partitions them across six specialists so each can hold a tight prompt, and aggressively prunes false positives in synthesis. Severity calibration matters more than raw recall — a list of fifty nits buries the one critical finding.

What gets reviewed

The skill works on any of the following review scopes. If the user did not specify, ask once which scope they want.

For all scopes: also collect the relevant context — the analysis's UPPER_SNAKE_CASE.md documentation file, specification.md if present, .living/decisions.md, and any installed convention packs in .living/conventions/ — and pass these into each sub-agent so it can ground findings in the project's stated intent rather than inferring from code alone.

Default mode protocol

Step 1 — Establish review scope

Determine the scope from the user's invocation. If unclear, ask one short question ("review the working tree, last commit, or a specific PR?") rather than guessing. For PRs, fetch with gh. For commits/working tree, use git.

Capture the diff, the list of touched files, and any relevant context files into local variables (or a scratch file in /tmp/) so the sub-agents share a common substrate.

Step 2 — Dispatch six sub-agents in parallel (or run their checklists in-line)

If the Agent tool is available to you, schedule all six specialists while respecting the host capacity (subagent_type general-purpose is fine; for very large diffs prefer Explore). Run as many concurrently as the host permits, wait for that wave to finish, and dispatch the remaining specialists in later waves. Do not assume that six slots are available. If dispatch reports agent thread limit reached, wait for an active specialist to finish and retry the undispatched specialist once; if capacity remains unavailable, run that checklist in-line. If the Agent tool is not available (common when this skill runs from inside a sub-agent context that doesn't expose it), execute each specialist's checklist in-line: read each checklist file in turn, apply it to the diff, collect findings, then proceed to synthesis. Either way the output contract and the synthesis steps are the same, and every applicable checklist must run exactly once.

Each sub-agent (or in-line pass) gets:

1. The diff (or path to it if large)
2. The list of context files to read
3. The path to its checklist reference: skills/core/references/review/<agent>.md
4. A clear instruction to follow the output contract in

skills/core/references/review/README.md exactly. The required fields per finding are severity (major | minor), file, line (or range), category, summary, evidence (a 1–5 line verbatim code snippet — the synthesis pass renders this directly under each finding), why_it_matters (one or two sentences specific to this analysis), suggested_fix, and confidence (high | medium | low). Anything the agent considered and decided not to flag goes in a separate not_flagged list with file, line, considered, and reason — synthesis uses this to dedupe across agents. Sub-agents should also return a decisions list of consequential analytical choices in their scope (per the README contract); these roll up into the report's "Key decisions in this analysis" section.

1. The standing instruction to err on the side of NOT flagging when the

evidence is weak — false positives are more costly than false negatives at this stage because synthesis can ask follow-up questions but cannot reconstruct missing certainty.

The six sub-agents and their checklist files:

The bioinformatics agent should self-skip with a one-line "no biology here" if the diff doesn't touch genomic data — don't spawn it if the project clearly isn't biology, but err on the side of running it for any project that has ever touched a sequence file, gene table, or single-cell object.

Step 3 — Synthesize

Read skills/core/references/review/synthesis.md and follow it. The short form:

1. Aggregate findings across sub-agents and dedupe. Two sub-agents

flagging the same line with different framings is the common case — keep the more actionable framing and add a one-line "see also" if the other framing adds value. One root cause gets one finding ID even when it has several consequences, affected files, or remediation steps. Nest those details under that finding; do not inflate the total by splitting one defect into multiple framings.

1. Recalibrate severity to two levels: Major (fix this — result

invalid, misleading, or insecure) and Minor (consider improving — doesn't change the conclusion). Drop pure stylistic nits a linter would catch.

1. Identify the key analytical decisions in the work — the

consequential choices that, if changed, would meaningfully change the result (estimand, sample-filtering thresholds, normalization, model / test choice, multiple-comparison handling, train/test strategy, reference choice, etc.). List them whether or not each has an associated finding.

1. Draft 3–5 questions for the analyst — meta-level questions whose

answers change which findings matter most (e.g., "is this for wet-lab validation or paper figure?", "are donors technical or biological replicates?", "is the deployment seeing the same customers or new ones?"). The diff can't answer these.

1. For each finding, include: file:line, a 1–5 line code snippet

verbatim from the source so the user sees the issue without opening the file, why it matters for this analysis specifically, and a one-sentence fix.

1. Group findings by category (the six sub-agent areas), and within each

category list Major findings first, then Minor.

1. Number findings F1, F2, F3 ... globally so the Key decisions and

Questions sections can link to them where useful.

1. Derive every reported count from the final ##### F<n>. headings. Add the

required Finding tally table, then run the deterministic validator before reporting or writing a handoff: python3 "$(cat .mycelium/plugin-root)/skills/core/scripts/validate_review_report.py" <report>. If it fails, repair IDs, severities, or tallies and rerun it. Never copy an earlier draft's hand-count into chat or .mycelium/last-session.md.

Step 4 — Render the report

Write the report to a file under .living/outputs/reviews/ named YYYY-MM-DD-<scope-slug>.md (e.g., 2026-04-24-pr-127.md, 2026-04-24-working-tree.md). The structure:

# Review — <scope> — YYYY-MM-DD
 
**Scope**: <PR / commit range / working tree / pasted diff>
**Files reviewed**: N
**Sub-agents run**: 6 (or list which were skipped and why)
 
## Key decisions in this analysis
 
-**<Decision>** — <one-line description>. <see F2 if linked, or no
  link if informational>
-...
 
## Questions for the analyst
 
Three to five open-ended questions whose answers would change which
findings matter most (analysis goal, replicate type, downstream use,
acceptable false-positive rate, registration status, deployment
context). The diff can't answer these — only the analyst can.
 
-<Question>
-...
 
## Findings
 
### Statistics & causal inference
#### Major
##### F1. <short description>
`<file>:<line>`

<1-5 lines verbatim>

**Why it matters here**: ...
**Fix**: ...
 
#### Minor
##### F2. ...
 
### Data pipeline & leakage
... (Major / Minor under each category)
 
### Bioinformatics
...
 
### LLM coding antipatterns
...
 
### Documentation & schema fidelity
...
 
### Code quality
...
 
## What was checked but is fine
- **Statistics & causal inference**: <one sentence>
- ...
 
## Finding tally
 
| Category | Major | Minor | Total |
| --- | ---: | ---: | ---: |
| Statistics & causal inference | N | N | N |
| Data pipeline & leakage | N | N | N |
| Bioinformatics | N | N | N |
| LLM coding antipatterns | N | N | N |
| Documentation & schema fidelity | N | N | N |
| Code quality | N | N | N |
| **Total** | **N** | **N** | **N** |
 
## Notes
- Cross-cutting observations: compound findings sharing one remediation
  path, "did this code ever run" questions, etc.