Field off option

.claude/commands/parallel-audit.md

@@ -0,0 +1,148 @@
+---
+description: Spawn N parallel Explore agents on independent slices of the repo, then synthesize findings into a prioritized punch list
+argument-hint: <topic> [--agents N]
+allowed-tools: Agent
+---
+
+# Parallel codebase audit
+
+Fan out `N` Explore subagents on **independent** slices of the repo,
+each producing a tight punch list, then synthesize the returns into a
+single prioritized list with `[critical|high|medium|low]` tags and
+file:line citations.
+
+This pattern is the right tool when:
+- The question spans the codebase (>3 directories or surfaces).
+- The agents' work is mostly independent — overlap wastes tokens.
+- The user wants concrete, citable findings, not a tour.
+
+It is **not** the right tool when the answer is in one file
+(use Read), one symbol (use Bash grep), or already known
+(answer directly).
+
+## Usage
+
+```
+/parallel-audit <topic> [--agents N]
+```
+
+- `<topic>` — what the audit is about. Examples:
+  `"simplification opportunities"`,
+  `"unused code and dead imports"`,
+  `"test coverage gaps in utils/"`,
+  `"CLI ergonomic inconsistencies"`,
+  `"performance hot paths"`,
+  `"security review of subprocess calls"`.
+- `--agents N` — optional, default `4`. Cap at `6` (more invites
+  duplication and synthesis overhead).
+
+## Examples
+
+```
+# What this repo's biggest simplification wins are
+/parallel-audit "simplification opportunities"
+
+# Test gaps before adding CI
+/parallel-audit "test coverage gaps" --agents 3
+
+# Pre-PR security pass
+/parallel-audit "security review: subprocess, SQL strings, file paths"
+```
+
+## Instructions
+
+You are given `$ARGUMENTS`. Follow these steps.
+
+### 1. Parse args
+
+- First non-flag token sequence (until a `--` flag) is the `TOPIC`.
+- `--agents N` sets the agent count; default `4`, clamp to `[2, 6]`.
+
+### 2. Pick the slicing dimensions
+
+Choose `N` **non-overlapping** slices that together cover the topic.
+Slicing strategies (pick the one that fits the topic):
+
+- **By directory**: `bin/`, `utils/`, `data/`, `web/`, `tests/`,
+  `wiki/`. Best when the topic is breadth-first and mechanical.
+- **By concern**: code quality / CLI ergonomics / data layer /
+  hygiene+CI / docs. Best for "code review" type asks.
+- **By layer**: entry points / library / persistence / external IO.
+  Best for performance, security, error-handling.
+- **By risk**: critical paths / hot paths / cold paths. Best for
+  performance and reliability audits.
+
+Reject overlap. If two slices would inspect the same files for the
+same thing, merge them and pick a different fourth slice.
+
+### 3. Brief each agent
+
+Spawn all `N` agents in **a single message with N parallel tool
+calls** (not sequentially). Each brief must include:
+
+- The slice's scope (paths, file globs, or symbol patterns).
+- The exact question for this slice — narrow, not the umbrella topic.
+- The output contract:
+  - Top ~8 findings, prioritized.
+  - Each finding: `file:line` + one-sentence problem +
+    one-sentence fix + severity tag `[critical|high|medium|low]`.
+  - Word cap (typically 500–600 words per agent).
+  - Final line: a one-sentence "biggest single win" recommendation.
+- What to **skip** (the slices owned by sibling agents) — prevents
+  duplication.
+
+Do not delegate synthesis. Each agent reports raw findings; the
+lead (you) ranks and dedupes.
+
+### 4. Synthesize
+
+Once all agents return:
+
+1. Collect findings, **dedupe** items mentioned by multiple agents
+   (these are higher-confidence — flag them).
+2. Group by severity, then by theme.
+3. Trim noise: cosmetic style, hypothetical "what-ifs", anything
+   without a file:line citation.
+4. Verify any surprising claim before including it. Agent reports
+   can be wrong about file contents — when an agent's claim drives
+   a destructive recommendation, run a quick `Read`/`grep` first.
+5. End with a clear "if you do one thing, do this" recommendation
+   and explicit ROI ordering.
+
+### 5. Report
+
+Produce the punch list in the conversation. Format:
+
+```
+## [Severity] — [Theme]
+1. [file:line] [problem]. [Fix].
+2. ...
+
+## Biggest leverage if you do one thing
+[One paragraph, named action, expected ROI.]
+
+Want me to start on [#N]?
+```
+
+Keep the synthesis tight — usually under 800 words. Long synthesis
+defeats the point of fanning out.
+
+## Notes
+
+- The audit is **read-only**. Do not let agents edit files. The
+  Explore subagent type already enforces this; if you use a
+  general-purpose agent, say so explicitly in the brief.
+- This skill is for **breadth**, not depth. For deep dives on a
+  specific bug, use a single agent with full context, not parallel
+  ones with partial context.
+- Agents do not see the conversation history. Briefs must be
+  self-contained — no "based on what we discussed" references.
+- The synthesis lives in the lead conversation, not in any agent.
+  Don't ask an agent to "synthesize the others' findings" — they
+  can't see them.
+- If an agent returns "nothing notable", trust it. A clean slice
+  is information; don't pad the punch list to look thorough.
+- For Mu2e prodtools specifically, the canonical 4-slice cut is:
+  `utils+bin code quality / CLI ergonomics+EXAMPLES.md drift /
+  DB schema+JSON configs / tests+repo hygiene`. Use this as the
+  default unless the topic argues otherwise.

.claude/commands/poms-push.md

@@ -0,0 +1,171 @@
+---
+description: Plan a production POMS push — pick the right map number (extend existing in place vs allocate new) before delegating to /mu2epro-run
+argument-hint: <json-config> --dsconf <dsconf> [--workflow <pattern>] [SIMJOB_VERSION]
+allowed-tools: Bash, Read
+---
+
+# Plan a production POMS push
+
+Decides whether a `--prod --jobdefs <map>` push should **extend an
+existing POMS map in place** or **allocate a new map number**, based
+on whether the workflow's earlier stages already live in a map.
+Prints the recommended `/mu2epro-run` invocation; does **not** push.
+
+The PBI chain is the canonical example: stages 1+2 already in
+`MDC2025-025.json` → stage 3 reco must extend `025`, not allocate
+`026`. This skill exists because that mistake was made on
+2026-04-25 and remediation required deleting an orphan SAM index;
+the convention is now codified here.
+
+## Usage
+
+```
+/poms-push <json-config> --dsconf <dsconf> [--workflow <pattern>] [SIMJOB_VERSION]
+```
+
+- `<json-config>` — relative path to a prodtools JSON config (e.g.
+  `data/mdc2025/reco.json`); resolved against the repo root.
+- `--dsconf <dsconf>` — required; the dsconf `json2jobdef` will use
+  (e.g. `MDC2025ai_best_v1_3`). Used to (a) filter the JSON config
+  entries that will be pushed, and (b) forward to `/mu2epro-run`.
+- `--workflow <pattern>` — optional substring or glob to match
+  against existing tarball descs (e.g. `PBI`, `PBI*_33344`,
+  `CeEndpoint`). If omitted, derived from the config's `desc` /
+  `tarball_append` fields.
+- `SIMJOB_VERSION` — optional SimJob version tag (e.g. `MDC2025ai`,
+  `Run1Bag`); default `Run1Bag`. Forwarded to `/mu2epro-run`.
+
+## Examples
+
+```
+# Auto-derive workflow from data/mdc2025/reco.json desc fields
+/poms-push data/mdc2025/reco.json --dsconf MDC2025ai_best_v1_3 MDC2025ai
+
+# Explicit workflow pattern (skip auto-detection)
+/poms-push data/mdc2025/digi.json --dsconf MDC2025ai --workflow PBI MDC2025ai
+
+# Brand-new workflow (no prior stages in any map)
+/poms-push data/mdc2025/stage1.json --dsconf MDC2025aj --workflow NewThing MDC2025aj
+```
+
+## Instructions
+
+You are given `$ARGUMENTS`. Follow these steps.
+
+### 1. Parse args
+
+- Locate `--dsconf <value>`. **Error and stop** if missing.
+- Locate `--workflow <value>` (optional).
+- Locate a SimJob version tag — first positional token matching
+  `^[A-Z][A-Za-z0-9_]+$` and not a `--flag`; e.g. `MDC2025ai`,
+  `Run1Bag`. Default `Run1Bag`.
+- The first remaining positional arg = `<json-config>` (relative
+  path). Resolve it against the repo root (`cwd` at invocation
+  time) into an absolute path `JSON_ABS`.
+- Validate `JSON_ABS` exists; error if not.
+
+### 2. Determine the workflow pattern
+
+If `--workflow <pattern>` was given, use it verbatim. Otherwise:
+
+a. Read `JSON_ABS`. The config is either a list of entries or a
+   single entry. Filter to only entries whose `dsconf` matches
+   `<dsconf>` (entries can hold `dsconf` as a string or a one-element
+   array). If no entries match, error and stop.
+
+b. From each filtered entry, extract a "workflow root" token:
+   - Prefer `desc` field if present.
+   - Else infer from `input_data` keys: parse `<tier>.<owner>.<desc>.<dsconf>.<ext>`,
+     take the `desc` portion.
+   - Strip any of these stage-suffix patterns from the right end
+     (longest first):
+     `Mix1BBTriggered`, `Mix1BBTriggerable`, `Mix2BBTriggered`,
+     `Mix2BBTriggerable`, `Mix1BB-reco`, `Mix2BB-reco`,
+     `Mix1BB`, `Mix2BB`, `OnSpillTriggered`, `OffSpillTriggered`,
+     `OnSpill`, `OffSpill`, `Triggered`, `Triggerable`, `-reco`,
+     `Cat`. Iterate until none match.
+   - Also account for the entry's `tarball_append` (e.g. `-reco`)
+     by ensuring it's stripped.
+
+c. Take the **longest common prefix** of the resulting roots
+   (case-sensitive). Examples:
+   - `PBINormal_33344`, `PBIPathological_33344` → `PBI`
+   - `CeMLeadingLog`, `CePLeadingLog` → `Ce`
+   - `FlatGamma`, `FlatGammaCalo` → `FlatGamma`
+
+d. If the common prefix is shorter than 3 chars or empty, **stop
+   and ask** the user for `--workflow` explicitly. Don't guess.
+
+Print the derived pattern with one-line rationale.
+
+### 3. Scan existing maps
+
+- Run: `ls /exp/mu2e/app/users/mu2epro/production_manager/poms_map/MDC2025-*.json`.
+- Keep only files whose basename matches `^MDC2025-\d{3}\.json$`
+  (exactly 3 digits). This excludes test variants (`-test`,
+  `-test2`, `-tes`), special names (`-MDS3c`), and any other
+  naming oddity in one stroke.
+- For each remaining map, read it and extract every `tarball` value
+  (each entry has one). For each tarball name, parse out the desc
+  portion: `cnf.<owner>.<desc>.<dsconf>.<v>.tar` → `<desc>`.
+- Count how many tarballs in each map have a `<desc>` that
+  **contains the workflow pattern as a substring** (case-sensitive).
+
+### 4. Decide the map
+
+- **Exactly one non-test map has ≥ 1 matching tarball** →
+  *extend in place*. Target = that map's path.
+- **Multiple maps match** → stop and ask which one to extend.
+  Show each candidate with its match count and a sample tarball.
+- **Zero maps match** → *allocate next free number*:
+  - Across all `MDC2025-NNN.json` matching `^MDC2025-\d{3}\.json$`,
+    take `max(NNN) + 1`, format as 3-digit zero-padded.
+  - Target = `/exp/mu2e/.../poms_map/MDC2025-<NNN>.json` (does
+    not exist yet; `json2jobdef --prod --jobdefs <path>` will
+    create it).
+
+### 5. Report and stop
+
+Print exactly this shape:
+
+```
+Workflow pattern: <pattern>  (source: <--workflow flag | derived from desc>)
+Existing maps:
+  MDC2025-NNN.json — <K> matching tarballs  (sample: <one-tarball>)
+  ...
+Decision: <extend MDC2025-NNN.json in place | allocate new MDC2025-NNN.json>
+Reason: <one-liner>
+
+Recommended command:
+
+  /mu2epro-run <SIMJOB_VERSION> json2jobdef \
+      --json <JSON_ABS> \
+      --dsconf <dsconf> \
+      --prod \
+      --jobdefs /exp/mu2e/app/users/mu2epro/production_manager/poms_map/MDC2025-NNN.json
+```
+
+**Do not invoke `/mu2epro-run` yourself.** Print and stop. The user
+inspects the decision and runs the command next. This keeps the
+existing production-push confirmation gate in `/mu2epro-run` exactly
+where it is.
+
+## Notes
+
+- Read-only by design — does not modify maps, push tarballs, call
+  samweb, or change SAM definitions.
+- `-test.json` maps are skipped intentionally. If a test-mode push
+  is needed, pass `--workflow <test-pattern>` explicitly and target
+  a `-test` map by hand.
+- The longest-common-prefix heuristic can over-match (e.g. `Ce`
+  catches both `CeEndpoint` and `CeMLeadingLog` workflows). If the
+  derived pattern matches multiple unrelated maps, the skill stops
+  per step 4 and asks. Pass `--workflow` to disambiguate.
+- If the JSON config has multiple `dsconf` values, only the entries
+  matching the supplied `--dsconf` are used to derive the pattern
+  (mirrors what `json2jobdef --dsconf` will do at push time).
+- This skill encodes the convention in
+  `feedback_extend_existing_poms_map.md` (memory) and the Stage 3
+  "Process note" subsection of
+  `wiki/pages/pbi-sequence-workflow.md`. If the convention changes,
+  update both alongside this skill.