| name | red-pen |
| description | Independent red-team review for Firefox root-cause analyses and proposed fixes. Use to critique an analysis, patch, Phabricator revision, commit, diff, or working tree with isolated Codex subagents and structured verdicts.
|
| metadata | {"short-description":"Independent fix review"} |
RedPen
Get an independent second opinion on a proposed RCA solution before it
goes in front of a human reviewer or the user.
The reviewer runs in an isolated subagent context — it does not see the
calling agent's conversation, memory, or prior conclusions. Inputs are passed
by file path only. This is the dotfiles equivalent of bringing in an
outside engineer: no anchoring on what's already been decided, no rubber
stamping.
The reviewer's primary job is to find a more elegant fix if one exists,
including fixes that redesign the surrounding codebase when the right design
would resolve the root cause and other latent issues at once.
Inputs contract
This skill accepts conclusions only by file path. Do not summarize or
restate the analysis in the prompt — the reviewer must read it themselves.
Arguments: $0
Tokens are classified by shape. Disambiguation priority — apply per
token, in order; first rule that matches wins:
- Token resolves to an existing file (try as-given, then relative to
CWD, then absolute):
*.md → markdown role (see role assignment below).
*.patch / *.diff → solutions source (distiller required).
- any other extension or extensionless → ask the user directly. Do not guess.
bug:<digits> / bz:<digits> / https://bugzilla.mozilla.org/show_bug.cgi?id=<digits>
→ analysis source (intake required).
D<digits> / https://phabricator.services.mozilla.com/D<digits>
→ solutions source (distiller required).
https://github.com/<owner>/<repo>/pull/<n>
→ solutions source (distiller required).
- URL ending in
.patch or .diff
→ solutions source (distiller required).
- Literal
diff (and no file by that name in CWD)
→ solutions source: uncommitted working tree.
- Literal
local or HEAD (and no file by that name in CWD)
→ solutions source: branch tip vs git merge-base.
- Token resolves to a git commit
(
git rev-parse --verify "$tok^{commit}" succeeds)
→ solutions source: that commit.
--desc <text> flag → analysis source: user free-text. The skill writes
the text to a scratch file before invoking intake.
- None of the above → ask the user directly. Never silently fall back.
Role assignment for markdown files: at most one analysis md and one
solutions md per invocation. First *.md token (in argument order) →
analysis; second *.md → solutions. A third *.md is rejected unless its
basename ends with -review.md, in which case it is the explicit output
path.
Conflict rule: at most one analysis source and one solutions source per
invocation. Two analysis-side or two solutions-side tokens →
ask the user directly. Never silently pick a winner.
Output path resolution (priority order):
- Explicit token ending
-review.md.
- If any user-supplied
*.md was given:
<dirname(that md)>/<bug-id-stripped-basename>-review.md. Bug-id-strip
rule: if basename matches ^bug-(\d+)-analysis$, strip -analysis
first — so sherlock's bug-12345-analysis.md produces
bug-12345-review.md.
- Else if a bug id is derivable (from
bug:<id>, from front-matter of a
scratch analysis doc, or from a Phab revision's commit message):
$PWD/bug-<id>-review.md.
- Else
$PWD/red-pen-review-<run-id>.md.
Print the resolved output path before invoking the critic so the user can
abort.
If after parsing there is no analysis source, ask the user directly. Do not
guess.
Adapter step (only when non-md sources present)
If every supplied source is already an existing *.md file, skip this
section entirely and go to Pre-flight. (Sherlock Phase 2 always passes
two *.md paths, so it never triggers an adapter spawn.)
Otherwise, normalize non-md inputs into markdown docs in a scratch
directory at ~/.codex/red-pen-scratch/<run-id>/, where <run-id> is
<bug-id-or-arg-hash>-<utc-timestamp>-<4-char-suffix>. The scratch dir
persists after the run for debugging; it is never auto-deleted.
Order is fixed and sequential. Each step waits for the previous to write
its output file before the next is invoked:
-
Intake — invoked only if no analysis md was supplied. Spawn one
red_pen_intake subagent:
spawn_agent(
agent_type: "red_pen_intake",
message: <descriptor + output-path + template-path; no conclusions>
)
Confirm the output file exists and is non-empty before continuing. If
intake reports an error, abort the skill — do not invoke the critic on
partial inputs.
-
Distiller — invoked only if no solutions md was supplied or the
solutions source is non-md (Phab revision, patch file, commit, working
tree, GitHub PR, raw URL). Spawn one red_pen_distiller subagent, same
discipline as intake.
-
Critic — same invocation as in Spawn the reviewer below. The
resolved analysis-doc path and solutions-doc path (whether
user-supplied or scratch) are passed to the critic exactly as today.
The intake and distiller subagents each return only short summaries to
this skill (paths and metadata). Never quote the body of an
intake/distiller doc into the critic's prompt. The critic reads files by
path; the skill is just a path-handler.
Pre-flight
- Confirm the analysis doc exists and is readable (Read tool). For
adapter-produced scratch docs, this also confirms the adapter wrote
non-empty output.
- If a solutions doc was passed (or produced by the distiller), confirm
it exists.
- Resolve the output path per the rules in Inputs contract. If the
resolved path already exists, append
-N until unique (so re-running
the skill produces a new review, never overwrites).
- Identify the bug ID if present in the analysis doc (look for
Bug <id> in the title, summary, or front-matter). Used only for
naming.
Spawn the reviewer
Spawn one red_pen_critic subagent. Do not chain multiple reviewer calls —
one isolated review per skill run.
spawn_agent(
agent_type: "red_pen_critic",
message: <see template below>
)
Prompt template
The prompt MUST contain only file paths and instructions — never the
content of those files, never a summary of prior findings.
You are reviewing a proposed root-cause-analysis solution. You have NO prior
context — read every input fresh.
Inputs (read these directly with the Read tool):
- Analysis doc: <absolute path to analysis doc>
- Solutions doc: <absolute path to solutions doc, OR the same as analysis
doc with a note: "read the ## Proposed Solutions section">
- Repo root: <absolute path>
- Output path for your review: <absolute path>
Your task:
1. Read the analysis doc and the solutions.
2. Verify cited file:line references against the actual source. Do not
trust any claim until you have re-read the cited code.
3. Search for a more elegant fix — including codebase redesigns when a
better design would also resolve other latent issues. See your system
prompt for what counts as a redesign worth proposing.
4. Write your review to the output path using the structure in
<skill-dir>/references/review-template.md.
5. Return a 4-line summary in the format your system prompt specifies.
Hard rules:
- No prior context. Trust nothing until verified against source.
- No editing of code or patches.
- No phantom citations. Open the file or admit you couldn't.
Replace <skill-dir> with the absolute path to this skill's directory so the
reviewer can locate the template.
Result handling
When the reviewer returns:
-
Read the review doc at the output path (Read tool, single call).
-
Extract the verdict, headline finding, and iteration recommendation from
the review-doc front matter or first section.
-
Surface to the caller (whether human or another skill) with this exact
shape, no additional commentary:
**Independent review** ([review doc](<relative-path-to-review-doc>))
- Verdict: <verdict>
- Headline: <one-sentence headline finding>
- Iteration: <iteration recommendation>
-
Do not re-summarize the reviewer's reasoning. The review doc on disk
is the canonical artifact; both human and caller can read it directly. Re-
summarizing both wastes context and risks distorting the review.
When called from another skill
The calling skill should:
- Pass absolute paths only.
- Pass the analysis doc as it stands — do not pre-edit it to "look better"
for the reviewer.
- Wait for the review result before continuing its own workflow.
- Handle each verdict per its own rules. Common pattern (see sherlock Phase
2 for the canonical version):
approve → proceed.
approve-with-concerns / revise → apply changes, re-invoke if changes
are non-trivial.
redesign → escalate to user; do not silently expand scope.
reject / needs-more-info → loop back to the relevant analysis step.
Standalone use
A user can invoke this skill directly without a calling skill. Beyond the
classic "two markdown docs" form, any of the wider input shapes documented
in Inputs contract work standalone too:
red-pen bug:1234567 D45678 — review the Phabricator revision against
the Bugzilla bug.
red-pen <abs>/analysis.md foo.patch — review a colleague's patch file
against an existing analysis doc.
red-pen <abs>/analysis.md diff — review uncommitted working-tree
changes.
red-pen <abs>/analysis.md <commit-sha> — review a specific commit.
red-pen --desc "frob crashes on second call" diff — quick review
against a free-text problem description.
Useful for vetting a proposed fix from a colleague's RCA write-up, a
Phabricator revision out for review, or your own in-progress changes
before posting.
Hard rules for this skill
- Never include conclusions in the reviewer prompt — only paths. The same
applies to the intake and distiller subagent prompts: pass descriptors
and output paths, never embed prior analysis or summaries.
- Never invoke
red-pen-critic more than once per skill run. The adapter
subagents (red-pen-intake, red-pen-distiller) are each invoked at
most once, and only before the critic. Order is fixed: intake →
distiller → critic, sequential. None run in parallel. If the caller
wants iteration, it invokes the skill again with revised inputs.
- Never modify the analysis doc or solutions doc, nor any user-supplied
source artifact (Bugzilla bug, patch file, git commit, working tree,
remote repo). The skill writes the review doc and any number of scratch
transport docs in
~/.codex/red-pen-scratch/<run-id>/; everything
else is read-only.
- The distiller doc is mechanical-only (provenance + raw diff). Do not
let the distiller editorialize. The critic reads the diff itself; it
does not need a human-readable summary.
Future work
red-pen-loop (deferred). An iteration-driver skill that reads the
verdict and either re-invokes the critic on revised inputs
(approve-with-concerns, revise) or surfaces to the user (redesign,
reject, needs-more-info). Two open design questions block this:
(1) the revise verdict needs an "applier" subagent that mutates a
copy of the solutions doc without violating the no-mutation rule
above; (2) sherlock already encodes the verdict-ladder loop in its
Phase 2, so a generic loop skill is only worth building once a
non-sherlock caller appears. Build separately; do not embed iteration
logic in this skill.