Codex compatibility note:
- Invoke repository skills with
$skill-namein Codex; this mirrored copy rewrites legacy Claude/skill-namereferences.- Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes.
- User-question prompts mean to ask the user directly in Codex.
- Ignore Claude-specific mode-switch instructions when they appear.
- Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written.
- Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required
spawn_agentsubagent(s) for that task.- Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first.
- For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence.
- If a required step/tool cannot run in this environment, stop and ask the user before adapting.
Codex Project-Reference Loading (No Hooks)
Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing.
Always read:
docs/project-config.json(project-specific paths, commands, modules, and workflow/test settings)docs/project-reference/docs-index-reference.md(routes to the fulldocs/project-reference/*catalog)docs/project-reference/lessons.md(always-on guardrails and anti-patterns)
Missing/stale context route: If docs/project-config.json, the docs index, lessons.md, CLAUDE.md, AGENTS.md, or any task-required reference doc is missing or stale, auto-run $project-init or the narrow setup route ($project-config, $docs-init, $scan-all, $scan --target=<key>, $claude-md-init) before ordinary project-specific work. If Codex mirrors or AGENTS.md are missing/stale, ask the user to run $sync-codex; do not auto-run it.
Situation-based docs:
- Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra):
project-structure-reference.md - Backend/CQRS/API/domain/entity changes:
backend-patterns-reference.md,domain-entities-reference.md - Frontend/UI/styling/design-system:
frontend-patterns-reference.md,scss-styling-guide.md,design-system/README.md - Spec authoring,
docs/specs/pathing, or TC format:feature-spec-reference.md,spec-system-reference.md,spec-principles.md - Behavior/public-contract changes or spec-test-code sync:
workflow-spec-test-code-cycle-reference.mdplus the spec docs above - Derived spec indexes/ERDs/reimplementation guides:
spec-system-reference.mdand source Feature Specs underdocs/specs/ - Integration test implementation/review:
integration-test-reference.md - E2E test implementation/review:
e2e-test-reference.md - Code review/audit work:
code-review-rules.mdplus domain docs above based on changed files
Do not read all docs blindly. Start from docs-index-reference.md, then open only relevant files for the task.
[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking: set
in_progresswhen step starts, setcompletedwhen step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.
Quick Summary
Goal: Stand up configurable, local-dev-only test-data seeders — enabled by default ONLY on local/dev — that auto-seed each feature's happy-path scenarios by calling the same public entry-point application commands a real user / QC tester would (NEVER direct DB writes), so the system self-tests its main cases like a QC engineer exercising them by hand; a configurable seed count repeats each scenario to BOTH cover the main cases AND enrich data volume (many simulated users) for performance testing + realistic first-time-init data, idempotent + restart-safe (never re-seeds already-seeded data; resumes from the last count toward target X, at 50% → continue until X), defaulting the count small when nothing is configured — and ALWAYS finding the project's existing seed-data convention FIRST.
Summary:
- Find the existing convention FIRST. Before designing anything, discover the project's seeder base class, env-gate key, count config key, and registration with
file:lineevidence (Step 1) — match it exactly; never invent a parallel mechanism. - Seeders orchestrate the real app pipeline like a real user: invoke the public entry-point application commands (which own validation, domain logic, and event side-effects) — never repo/DB inserts for domain entities, never duplicate command logic in the seeder.
- Dual purpose, one mechanism — a configurable count: repeat each happy-path scenario N times to (a) self-test the main cases (QC mimic) and (b) enrich data volume for many-users / performance / first-init realism. Read the count from config (never hardcode); default small when unset; zero → no-op.
- Four non-negotiable gates in order: (1) environment gate as the FIRST check (local-dev/enabled-config only), (2) count-before-seed idempotency (no re-seed when already seeded), (3) restart-safe loop from
existing_counttotarget_count(never 0 — resume the remainder after stop/restart), (4) scoped DI per iteration — a shared scope silently corrupts the DbContext/session. - Always pre-read
docs/project-reference/seed-test-data-reference.md+ project-configData Seedersgroup, then close with a fresh zero-memorycode-reviewerround; re-review fully only after a validated fix. - Two modes — surface the flag: default Generate (implement / enhance / fix a seeder);
--mode=review= READ-ONLY convention audit grading a target (prompt → current changes → work-context) against EVERY universal rule + project conventions withfile:linePASS/FAIL — routes confirmed fixes back to Generate, NEVER edits the seeder itself. - Main steps to run (Generate, in order — do not skip): Phase 0 detect task type (new/enhance/fix) → Step 1 discover conventions (base class, env-gate key, count key, registration) → Step 1.5 verify dev-config keys exist → Step 2 feature scope + application commands → Step 3 find/create seeder → Step 4 implement (env-gate FIRST → config count → idempotency → restart-safe loop → scoped DI) → Step 5 validate every gate with
file:line→ Step 7--mode=reviewself-audit on the changed code → freshcode-reviewerround →$changes-review(final).
Workflow (Generate mode — default):
- Phase 0 — Detect seeder task type (new / enhance / fix)
- Step 1 — Discover project seeder patterns, env gate key, count key
- Step 2 — Analyze feature scope + application commands
- Step 3 — Find or create seeder file
- Step 4 — Implement using language-agnostic algorithm
- Step 5 — Validate against universal rules
- Self-Review — Re-run THIS skill in
--mode=reviewover the changed seeder code (convention gate) - Review — Fresh sub-agent review round, then hand off to
$changes-review
Modes:
- Default (generate) — implement / enhance / fix seeders. Everything in the Generate-mode Protocol below applies. The generate-mode task plan MUST end by re-running this skill in
--mode=review(Step 7) BEFORE the$changes-reviewhand-off. --mode=review(read-only convention audit) — review a target against EVERY universal seed-data rule AND the project-specific seeder conventions, withfile:lineevidence and a PASS/FAIL verdict. Makes NO code changes; reports findings and routes confirmed defects back to generate mode for the fix. See Mode: Review.
Key Rules:
- ALWAYS find the project's existing seed-data convention FIRST — read
docs/project-reference/seed-test-data-reference.mdanddocs/project-config.json(Data Seederscontext group) before writing any seeder changes; match the discovered pattern, never invent a new one - ENABLE seeding by default ONLY on a local/development environment — the environment gate is the FIRST check, NEVER production
- SEED like a real user / QC tester — call the public entry-point application commands; NEVER call repository/DB directly for domain data
- NEVER duplicate command logic — seeder orchestrates, commands own validation
- ALWAYS make the seed count configurable and read it from config (NEVER hardcode); default to a small number when nothing is configured; zero → no-op
- A configurable count serves BOTH goals — self-test the main happy-path cases AND enrich data volume (many simulated users) for performance testing and realistic first-time-init data
- GUARANTEE idempotency — check count before seeding; never re-seed already-seeded data on restart
- ALWAYS loop from
existing_counttotarget_countso stop/restart resumes the remainder (target X, at 50% → continue until X), never re-seeding from 0 - SEED only states the application could actually produce — application-level operations guarantee reachability by construction; a direct store write fabricating an otherwise-unreachable state MUST be commented with why it is legitimate, and seeded entities MUST carry plausible relative timing rather than one shared instant
Mode Routing (FIRST decision)
Before Phase 0, route on the invocation flag:
| Signal | Mode | Go to |
|---|---|---|
--mode=review flag, OR prompt asks to review/audit/check a seeder |
Review | Mode: Review |
| Any other invocation (implement / enhance / fix a seeder) | Generate (default) | Phase 0 below |
MUST ATTENTION Generate mode OWNS the fix; Review mode is READ-ONLY and only reports. When Review mode finds a defect, it routes the fix back through Generate mode — it never edits the seeder itself.
Phase 0: Detect Seeder Task Type (Generate mode)
Before any other step, classify the request:
| Task Type | Detection | Action |
|---|---|---|
| New seeder | No existing seeder for feature area | Create following discovered base class pattern |
| Enhance existing | Seeder exists, needs new scenarios | Read existing seeder, add without breaking |
| Fix broken | Seeder fails env gate / idempotency / DI scope | Diagnose via Universal Rules, fix at root |
| Unknown | Request ambiguous | Ask user — NEVER assume |
rg "{Feature}Seeder|{Feature}SeedData|{Feature}TestData" {configured-source-roots} -l
Universal Seed Data Rules
Rule 0 — Convention First (priority before all others): ALWAYS discover and follow the project's EXISTING seed-data convention before doing anything — base class, env-gate key, count config key, registration, seeder marker. Match it with
file:lineevidence; never invent a parallel mechanism. If no convention exists, propose the smallest one that fits the project's stack.
- Environment Gate (local-dev default-only) — First check in seeder. Enabled by DEFAULT only on a local/development environment (or an explicit enable-config flag). NEVER seeds in production. The purpose is auto-setting-up feature test data on local/first-init, not a production data path.
- Command-Based (mimic a real user / QC tester) — Seeds by calling the same PUBLIC entry-point application commands a real user or QC engineer would invoke, via the full pipeline (validation + domain logic + events). This is automated happy-path self-testing. NEVER direct DB/repo writes for domain entities.
- No Duplicate Logic — Seeder provides realistic inputs. Commands own validation, domain logic, event side-effects.
- Idempotency (no re-seed when already seeded) — Check existing count → calculate remaining → seed only the difference. On restart with data already seeded, seed NOTHING. Running N times converges to the target, never duplicating.
- Count-Configurable (dual purpose, small default) — Read the seed count/times from the project config key (discovered Step 1); NEVER hardcode. Default to a small number when nothing is configured. The same count serves BOTH goals: repeating each scenario like a QC tester running it many times exercises the main cases AND enriches data volume (many simulated users) for performance testing and realistic first-time-init data. Zero → no-op.
- Restart-Safe (resume from last count) — Supports stop/start/restart any number of times: the loop runs from
existing_counttotarget_count, so if the target is X and only 50% of X is currently seeded, it continues until X is reached — never restarting from 0. - Real-World Reachable State (seed only what the app could produce) — Every seeded entity MUST represent a state the application itself could have produced. This is the deeper reason Rule 2 exists: an application-level operation can only ever leave reachable state behind. Where a direct store write is genuinely unavoidable, it MUST carry a comment stating WHY that state is legitimate (bootstrapping legacy/migrated data, an externally-owned record, a deliberately corrupt fixture for repair testing) — unexplained, it is a defect, not a fixture. Seeded entities MUST also carry plausible relative timing: stagger creation/update/activity stamps across a realistic span instead of stamping every record with one shared instant. — why: a corpus the application could never produce makes every test over it prove nothing, and a corpus where everything happened in the same millisecond hides ordering defects and makes time-window, sort, and pagination behaviour untestable.
- Spec-Consistent (Spec-Loop Discipline — tailored) — Seeders are orchestration, NOT business logic, so property/metamorphic generation and the MUTATION-SCORE gate are N/A here — do not force them. Apply the dual-feedback half: every seeded scenario MUST stay consistent with the §5 invariants (commands own validation; a seeder that produces state violating an invariant is a bug, not a fixture). If a seeder encodes a domain rule — a required precondition, a status/relationship the scenario assumes, a business default — that rule belongs in the spec, not silently in the seeder: feed it into BOTH the spec (the rule) AND, where it is testable, the tests — never a seeder-only fix.
Protocol (Generate mode)
Generate-mode Task Plan (task tracking — required)
MUST ATTENTION task tracking ALL of these BEFORE the first edit. The plan ALWAYS ends with a
--mode=reviewself-audit, and--mode=reviewALWAYS precedes the$changes-reviewhand-off — changes-review stays the final step.
- Discover seeder patterns, env-gate key, count key (Step 1) —
file:lineevidence. - Verify dev config has env-gate + count keys (Step 1.5).
- Analyze feature scope + application commands (Step 2).
- Find or create the seeder file (Step 3).
- Implement using the language-agnostic algorithm (Step 4).
- Validate against the universal rules (Step 5) —
file:linefor every gate. - Self-review the changed seeder code by re-running THIS skill in
--mode=review(convention gate over the just-changed code — MUST be a task, not optional). Fix any FAIL through this generate flow, then re-review. - Fresh zero-memory
code-reviewerround (Review Loop). - Hand off to
$changes-review(final step — review all changes before commit). - Analyze AI mistakes & lessons learned.
Step 1: Discover Seeder Patterns
Search for project seeder conventions:
# Search configured source roots using the repository's discovered seed-data naming conventions
rg "{configured-seeder-interface-or-base-patterns}|seeder|SeedData|DataSeed" {configured-source-roots} -l
Record with file:line evidence:
- Seeder base class / interface
- Seeder registration mechanism (DI, module, startup hook)
- Environment gate method/key name
- Count multiplier config key name
Step 1.5: Verify Dev Config Keys
Confirm dev config has both env gate key and count key. If absent, add following project's dev config convention. — why: missing keys silently disable the gate or count, producing no-op or unbounded seeding.
Step 2: Feature Scope Analysis
Identify before writing any code:
- Feature area — domain entity/aggregate being seeded
- Application commands —
rg "{Feature}.*Command|{configured-command-handler-patterns}" {configured-source-roots} -l - Dependencies — data must exist (users, orgs, prerequisite records)
- Scenarios — 3–5 realistic variations (standard, boundary, multi-actor)
- Target count — clarify: 1 scenario or N repetitions per scenario
Step 3: Find or Create Seeder
rg "{Feature}TestSeeder|{Feature}SeedingHelper|{Feature}TestDataSeeder" {configured-source-roots} -l
- Exists → enhance with new scenarios, do NOT break existing ones
- Absent → create following discovered base class pattern
Step 4: Implement
Algorithm (language-agnostic):
seeder():
if not is_local_development_environment(): return # default-enabled on local/dev only, NEVER prod
if not seed_enabled_in_config(): return # explicit enable flag (default on for local)
target = config.get("SeedCount", SMALL_DEFAULT) # configurable; small default when unset
if target <= 0: return # zero → no-op
existing = count_by_seeder_marker() # how much is already seeded
if existing >= target: return # idempotent: already seeded → seed NOTHING
for i from existing to target: # restart-safe: resume the remainder (e.g. 50% → target)
call_application_command(build_scenario_input(i)) # public entry command, like a real user / QC tester
Seeder marker — stable predicate identifying seeded vs user data:
- Email prefix, created-by field, name prefix, or dedicated boolean flag
- MUST be deterministic across restarts
Step 5: Validate
MUST ATTENTION verify all before complete:
- MUST ATTENTION environment gate is FIRST check —
file:lineevidence required - MUST ATTENTION count-before-seed idempotency gate present —
file:lineevidence - MUST ATTENTION loop starts at
existing_count, not 0 —file:lineevidence - MUST ATTENTION only application-layer commands used for domain entities — NEVER repo/DB
- MUST ATTENTION no business logic or validation duplicated in seeder
- MUST ATTENTION seeder registered via project DI mechanism —
file:lineevidence - MUST ATTENTION count config key read correctly (zero → no-op, NEVER hardcoded)
- MUST ATTENTION scoped DI per iteration — shared scope = DbContext/session corruption
- MUST ATTENTION every seeded state is one the application could actually produce; any unavoidable direct store write carries a comment justifying WHY that state is legitimate —
file:lineevidence - MUST ATTENTION seeded entities carry plausible relative timing (staggered stamps), NEVER one shared instant
Sub-Agent Routing
| Task | Sub-Agent | When |
|---|---|---|
| Discover seeders + commands across large codebase | general-purpose |
Steps 1-2 |
| Review seeder compliance | code-reviewer |
Round 1 post-implementation |
| Seeder handles credentials/PII | security-auditor |
Security-sensitive patterns |
| Seeder runs 1000+ records | performance-optimizer |
Performance-intensive |
All sub-agent prompts MUST include:
Graph DB active. After grep finds key files, run:
python .claude/scripts/code_graph trace <file> --direction both --json
Pattern: grep → trace → grep verify.
Anti-Patterns
| Anti-Pattern | Correct |
|---|---|
| Direct repo insert for domain entities | Call application command |
| Seeder validates business rules | Command owns validation; seeder provides valid inputs |
| No idempotency check | Check count first; seed only remaining |
Hardcoded count (for i in 0..10) |
Read count from config key (discovered Step 1) |
| No environment gate | Check project env gate key first |
| Shared DI scope across loop iterations | Use project's scoped DI per iteration (prevents DbContext corruption) |
| Seeded state no application operation could produce | Seed it through an application-level operation; if a direct write is unavoidable, comment WHY that state is legitimate |
| Every seeded record sharing one creation instant | Stagger stamps across a realistic span so ordering / time-window behaviour stays testable |
| Batch-all-then-write sub-agent findings | Persist findings per file; NEVER batch at end |
Review Loop
Round 1: After implementation, spawn fresh code-reviewer sub-agent with zero memory of implementation:
Review seeder at [file:path]. Verify with file:line evidence for each:
1. Environment gate is FIRST check
2. Idempotency: count-before-seed pattern present
3. Loop starts at existing_count not 0
4. Zero application-layer command bypasses (direct repo/DB = FAIL)
5. No hardcoded count — config key read
6. Scoped DI per iteration
Report: PASS or FAIL with file:line for each finding.
Fix loop: If FAIL → validate findings → fix validated findings → restart full review from first phase. When restarted review uses sub-agents, NEVER reuse them across rounds. If same blocker repeats across 2 full invocations with no progress, escalate to user. NEVER fix unvalidated findings. Do not spawn a fresh sub-agent only to re-review known findings before validation/fix.
Mode: Review (seed-data convention audit)
Invoke with
--mode=review. READ-ONLY audit of a seeder target against EVERY Universal Seed Data Rule AND the project-specific seeder conventions. Produces a per-principle PASS/FAIL withfile:lineevidence. This mode makes NO code changes — it reports findings and routes confirmed defects back to Generate mode for the fix.
R0 — Resolve the review target
Determine WHAT to review, in priority order:
- Explicit target in the user prompt — a named seeder file / class / feature area → review exactly that.
- Else → current changes —
git diff --name-onlyplus staged (git diff --cached --name-only) and untracked, filtered to seeder files using the discovered seeder naming (Step 1 / reference doc). Review every changed or added seeder. - Else → current work-context result — the seeder(s) created or edited earlier in THIS session / work context.
If none resolve → ask the user which seeder to review. NEVER assume a target.
R1 — Read the conventions BEFORE reviewing (BLOCKING)
MUST ATTENTION read, in full, before forming ANY verdict:
docs/project-reference/seed-test-data-reference.md— project seeder locations, base class, env-gate key, count config key, DI/UoW scope strategy, Required Patterns, Verification Checklist.docs/project-config.json→Data Seederscontext group — configured source roots, naming conventions, run commands.- The Universal Seed Data Rules (1–8) in this skill — the principles being graded.
- The target seeder file(s) themselves — re-read in full; NEVER review from memory.
- Step 1 discovery: confirm the project's ACTUAL seeder base class, env-gate key, and count key with
file:line— the review grades against THESE, not generic defaults.
If the reference doc is still a skeleton (
TODOplaceholders), say so explicitly, grade against discoveredfile:lineconventions instead, and raise the missing/incomplete project reference as its own finding.
R2 — Review checklist (grade EVERY item: file:line evidence or FAIL)
Universal rules:
- Environment gate is the FIRST check — dev/enabled-config only, NEVER production.
- Command-based — domain entities created ONLY via application-layer commands; ZERO direct repo/DB writes.
- No duplicated logic — seeder feeds realistic inputs; commands own validation / domain / event side-effects.
- Idempotency — count-before-seed gate present; running N times converges to target (no duplicates).
- Count-configurable — count read from the discovered config key; NEVER hardcoded (zero → no-op).
- Restart-safe loop — loop starts at
existing_count, NEVER 0. - Scoped DI per iteration — fresh scope per loop iteration; no shared DbContext/session.
- Real-world reachable state — every seeded entity is a state the application itself could produce; any direct store write fabricating an otherwise-unreachable state carries a comment justifying WHY it is legitimate; seeded entities carry plausible relative timing, not one shared instant.
- Spec-consistency — every seeded scenario satisfies the §5 invariants; any encoded domain rule (precondition / status / default) is reflected in the spec (and tests where testable), not seeder-only.
Project-specific conventions (from the reference doc):
- Seeder lives in the configured folder and extends the project's discovered base class / interface.
- Registered via the project's documented DI / registration mechanism.
- Env-gate key + count key match the documented keys AND exist in dev config.
- Seeder marker (email/name prefix, created-by, dedicated flag) is deterministic across restarts.
- Conforms to the reference doc's Required Patterns + Verification Checklist.
R3 — Verdict
Per item: PASS / FAIL / N/A with file:line evidence and confidence (>80% required to assert a FAIL; <60% → "insufficient evidence", verify before grading). Overall verdict is PASS only if ZERO universal-rule FAILs.
- PASS → report the evidence table; if idempotency/count tests are absent, suggest
$integration-test. - FAIL → list each violation with the responsible
file:lineand the correct pattern (from the Anti-Patterns table / reference doc). Route the fix back through Generate mode (Phase 0 → "Fix broken"); after the fix lands, RE-RUN--mode=reviewover the changed code. NEVER edit the seeder inside review mode.
Review-mode task plan (task tracking — required)
- Resolve the review target (prompt → current changes → work-context).
- Read
seed-test-data-reference.md+ project-configData Seedersgroup + Universal Rules + the target file(s). - Discover/confirm base class, env-gate key, count key with
file:lineevidence. - Grade every universal + project-specific checklist item (R2).
- Produce the PASS/FAIL verdict with per-item
file:lineevidence (R3). - If FAIL → hand confirmed defects to Generate mode and re-review after the fix; else report PASS + next-step suggestion.
- Analyze AI mistakes & lessons learned.
Workflow Recommendation
MUST ATTENTION — NOT IN WORKFLOW YET: Use ask the user directly:
- Activate
workflow-seed-test-data(Recommended) — scout → investigate → seed-test-data → changes-review → code-simplifier → docs-update- Execute
$seed-test-datadirectly — run this skill standalone
Next Steps
MUST ATTENTION after completing (Generate mode): use ask the user directly — do NOT skip. Step 7 self-review (
--mode=review) MUST have run on the changed code BEFORE these:
- "$workflow-review-changes (Recommended)" — final step: review all changes before commit (runs AFTER the
--mode=reviewconvention self-audit) - "$integration-test" — write tests verifying idempotency and count compliance
- "Skip, continue manually" — user decides
[IMPORTANT] task tracking for ALL tasks BEFORE starting. For simple tasks, ask user whether to skip.
Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.
Understand Code First — HARD-GATE: Do NOT write, plan, or fix until you READ existing code.
- Search 3+ similar patterns (
grep/glob) — citefile:lineevidence- Read existing files in target area — understand structure, base classes, conventions
- Run
python .claude/scripts/code_graph trace <file> --direction both --jsonwhen.code-graph/graph.dbexists- Map dependencies via
connectionsorcallers_of— know what depends on your target- Write investigation to
.ai/workspace/analysis/for non-trivial tasks (3+ files)- Re-read analysis file before implementing — never work from memory alone. — why: long context drifts from the file; the file is ground truth
- NEVER invent new patterns when existing ones work — match exactly or document deviation. — why: divergent patterns fragment the codebase and slow every future reader
BLOCKED until:
- [ ]Read target files- [ ]Grep 3+ patterns- [ ]Graph trace (if graph.db exists)- [ ]Assumptions verified with evidence
Evidence-Based Reasoning — Speculation is FORBIDDEN. Every claim needs proof.
- Cite
file:line, grep results, or framework docs for EVERY claim- Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend
- Cross-service validation required for architectural changes
- "I don't have enough evidence" is valid and expected output
BLOCKED until:
- [ ]Evidence file path (file:line)- [ ]Grep search performed- [ ]3+ similar patterns found- [ ]Confidence level statedForbidden without proof: "obviously", "I think", "should be", "probably", "this is because" If incomplete → output:
"Insufficient evidence. Verified: [...]. Not verified: [...]."
AI Mistake Prevention — Failure modes to avoid on every task:
Re-read files after context changes. Context compaction, resume, or long-running work can make memory stale; verify current files before acting. Verify generated content against source evidence. AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing. Check downstream references before deleting or renaming. Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first. Trace the full impact chain after edits. Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done. Verify ALL affected outputs, not just the first. One green check is not all green checks; validate every output surface the change can affect. Assume existing values are intentional — ask WHY before changing OR flagging one as a defect. Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard. Surface ambiguity before acting — don't pick silently. Multiple valid interpretations require an explicit question or stated assumption with risk. Assert the outcome your system owns, not the intermediate state your infrastructure owns. When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure. Keep shared guidance role-relevant. Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols.
Real-World Fidelity Gate — MANDATORY when authoring, reviewing, or repairing any integration / E2E / system test.
A test earns trust by reproducing a situation the system can actually meet in production. A scenario that could never occur in real life proves nothing when it passes, and wastes hours when it fails.
- Ask the fidelity question BEFORE writing the setup: "Can this sequence, timing, and data actually occur in production?" If no, the test is mis-specified — fix the SCENARIO, never the assertion.
- Model real pacing between actor steps. Two distinct actor actions that production separates by seconds, minutes, or hours MUST NOT be fired back-to-back in the same millisecond. Compressed pacing manufactures races the system was never designed to survive, then reports them as product defects.
- Wait on a real signal, never a blind sleep. Find an observable proving the prior step finished — a persisted state change, an audit/version stamp, a queue/worker idle marker, a completion event — and poll until it settles (unchanged across a short stability window). Use a fixed delay ONLY when no observable exists, and say so in a comment.
- Barriers belong in ARRANGE, never in ASSERT. Waiting for a precondition is fidelity. Widening an assertion's timeout, loosening a comparison, adding a retry around a failing assertion, or skipping the test is masking. NEVER do the latter to force green.
- Distinguish harness-amplified from real. Test topologies (shared infra, fan-out consumers, parallel suites, cold starts) can make a rare production race routine locally. Before filing a product defect, state whether the trigger exists in production and at what likelihood.
- Keep the protected invariant intact. Improving fidelity must NEVER reduce what the test protects. If a realistic scenario no longer exercises the rule, the rule needs a DIFFERENT realistic scenario — not a weaker assertion.
- Deliberate impossible-state tests are allowed, but MUST be labelled. Corruption-repair, migration, and fail-safe tests intentionally construct states production should never reach; comment WHY the state is reachable (upstream bug, partial write, legacy data), so they are never confused with unrealistic setups.
IMPORTANT MUST ATTENTION search 3+ existing patterns and read code BEFORE writing any seeder.
MUST ATTENTION cite file:line for every claim; declare confidence; "I don't have enough evidence" is valid output.
MUST ATTENTION apply critical + sequential thinking — every claim needs appropriate traced evidence (file:line for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence.
MUST ATTENTION apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting.
Prompt-Enhance Closing Anchors
IMPORTANT MUST ATTENTION follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval
IMPORTANT MUST ATTENTION for every step/sub-skill call: set in_progress before execution, set completed after execution
IMPORTANT MUST ATTENTION every skipped step MUST include explicit reason; every completed step MUST include concise evidence
IMPORTANT MUST ATTENTION if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses
Parallel Sub-Agent Dispatch — Plan parallelism the moment a task breakdown exists, BEFORE executing it — running provably independent tasks sequentially wastes wall-clock. Applies to every multi-step job: workflow steps, planning, batch updates, investigation, research, scans, reviews, doc sync. Plan execution is metadata-gated, NEVER default-parallel — fan-out follows ONLY what the plan declares (
PAR/SEQtags + per-phase write set); an untagged plan runs sequentially — why: a derived write set cannot see cascade or generated writes.
- Tag every task
PARorSEQ.PAR= inputs exclude every pending task's output AND write set disjoint from every otherPAR. ElseSEQ— MUST ATTENTION name the dependency forcing it.- Group
PARinto waves. No edge between members. Two writers of one file NEVER share a wave. Read-only work (search, investigation, review, research) parallelizes freely.- Declare before dispatch:
Parallel plan: wave 1 = [...] · wave 2 = [...] · SEQ = [...] (reason).- Spawn each wave in ONE message — every
spawn_agentcall in one response, NEVER dripped per turn. Route each task to its specialist (`.claude/skills/sh
…(truncated)