[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: Build configurable, local-development-only (default-enabled) seeders that exercise each feature's happy-path scenarios through public entry-point commands like a real user/QC tester (NEVER direct domain DB writes), repeat a configurable small-default count for case coverage and realistic data volume, remain idempotent and restart-safe, and ALWAYS follow the project's existing seed-data convention FIRST.
Summary:
Testability contract: resolve Unit/Integration/System/E2E applicability from runner/config evidence; record owner/root/data, copy-ready full + focused commands, zero-match behavior, CI/simple-Windows entry, unique run/data identity, and repeat proof; unresolved applicable fields block handoff, while non-applicable tiers require evidence-backed
N/A.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 is the default; --mode=review remains read-only and routes confirmed fixes back to Generate.
- 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. This count IS the volume knob
performance-reviewmeasures against (SYNC:engineering-foundation-gateF5): a perf claim needs ≥2 volumes ~10× apart to expose super-linear growth, and realistic shape — distribution, cardinality, skew — not N identical rows, because a hot-path query behaves differently against uniform data than against real skew - 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.
Persistent Seed Run Contract
For every persistent-data run, record this contract before Step 3 and carry it into the seeder's verification report:
- Public-path setup: arrange prerequisites and domain data through supported public application commands/queries like a real user or QC tester. Direct repository/DB writes are not an ordinary seed path; any documented impossible-state exception remains labelled and justified.
- Unique run identity: create one unique, non-sensitive
runIdentityper invocation and include it in synthetic business keys/values. A restart of the same run reuses that identity; an additive restart never mints a new batch. - Count-before-seed idempotency: query
existing_countby the deterministic seeder marker before creating anything, calculate the remainder, and no-op at/above the target. The target-mode loop starts atexisting_count, never zero. - Restart safety: after interruption, reuse the marker/run identity and create only missing keyed records; do not reset or delete persistent data to recover.
- Realistic valid data: every input must be valid and reachable through normal application behavior, with realistic relative timestamps/pacing rather than one shared synthetic instant.
- Explicit additive accumulation: declare
targetoradditivemode.targetconverges to the configured count;additiveis allowed only when explicitly required, preserves prior runs, appends new deterministic keys, and count-checks the current run batch for restart safety. - Integrity checks: report
before,created,after, the expected count equation, marker/key uniqueness, command success, and domain/reference invariants; any mismatch blocks completion. - Redaction: reports and logs contain only counts/status and a safe opaque run identity; redact credentials, tokens, authorization headers, connection strings, PII, and full fixture payloads.
Protocol (Generate mode)
Generate-mode Task Plan (TaskCreate — required)
MUST ATTENTION
TaskCreateALL 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
- MUST ATTENTION run identity, public-path setup, explicit target/additive mode, before/created/after integrity checks, and redacted evidence are present
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 that block the current round → restart full review from first phase. Round 1 treats every validated finding as blocking; from round 2 onward, a LOW-only result ends the loop with LOWs recorded under ## Deferred LOW Findings (severity floor, round ≥2), while CRITICAL/HIGH/MEDIUM and failed binary gates remain blocking. When restarted review uses sub-agents, NEVER reuse them across rounds. If the 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.
- Run identity and public-path setup — every run has a unique reusable identity, keyed synthetic values, and supported application-path arrangement.
- Accumulation and integrity —
targetvs explicitadditivemode is declared; additive runs preserve prior data and prove before/created/after counts, unique keys, command success, and invariant/reference integrity. - Redacted evidence — reports/logs expose only safe identifiers and exact counts/status; credentials, tokens, headers, connection strings, PII, and full payloads are redacted.
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 (TaskCreate — 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
AskUserQuestion:
- Activate
workflow-seed-test-data(Recommended) — investigate → seed-test-data → experience-review (conditional) → changes-review → code-simplifier → docs-update- Execute
/seed-test-datadirectly — run this skill standalone
Next Steps
MUST ATTENTION after completing (Generate mode): use
AskUserQuestion— 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]
TaskCreatefor 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.
Test Architecture & Execution Contract — Treat testability as a setup/architecture acceptance condition. For every potentially applicable tier — Unit, Integration/System, E2E, and Performance/Scale (warranted at
T1+/B2+) — recordAPPLICABLEonly with evidence of its runner/framework/configuration; otherwise recordN/A — <evidence>and never fabricate coverage.
- Matrix before implementation: Record applicability, owner, runner/framework, test root, fixture/data strategy, full command, focused/partial command, zero-match behavior, CI gate, a simple/Windows entry point (a
.cmdwhen the project needs one), the host-mode AND container-mode commands where the project supports both, and the environment reach (which of local / CI / production-shaped this tier can target).- Runnable scopes: Full and focused commands must be copy-ready, fail on invalid or zero-match selections, report exact counts and exit status, and be safe to repeat. E2E uses only configured browser/service commands.
- Fresh valid state: Each run/test owns a unique run identity and business-data suffix, arranges through supported public paths, and uses realistic valid data. Reference setup is count-before-create, idempotent, and restart-safe. Intentional accumulation is additive, keyed, and integrity-checked; never hide contamination with destructive reset. Run-scoped cleanup, when supported, is opt-in and idempotent: after evidence capture it may remove only ephemeral resources owned by the current run; it must never delete persistent/additive data or another run's data, reset shared state, or replace no-reset proof.
- Isolation and fidelity: Isolate mutable roots and parallel workers; share only immutable/reference data. Preserve real actor pacing and observable arrange barriers. Do not widen retries or weaken assertions to make a scenario pass.
- Evidence gate: Report command, scope, identity, seed/accumulation mode, exact result, and repeat proof. For each applicable persistent-state suite, require two consecutive no-reset full runs. Treat line coverage as diagnostic only; use meaningful property/invariant, mutation, change, and behavior coverage signals.
- Execution modes and environment reach: A tier claiming two run modes must have BOTH exercised — the bare-host command and the fully-containerized command, driven from ONE source of truth for config and topology; record which mode CI exercises, because an unexercised mode rots silently and a claimed-but-rotten mode is worse than one never claimed. The SAME suite must reach local, CI and (where warranted) a production-shaped target, parameterized by configuration, never by forked test code — only one fork ever stays maintained, so forking guarantees divergence. A target lacking a required capability reports
ENVIRONMENT-BLOCKED, never a silent pass. Tests unsafe against production are excluded by an ENFORCED mechanism whose absence fails loudly, not by a convention someone must remember; "runs in prod" means a safe, declared, NON-MUTATING subset. Reproducibility underwrites all of it — pinned toolchain, locked dependencies, declared external prerequisites — which is the difference between a suite that passes anywhere and one that passes on its author's machine. Depth →SYNC:engineering-foundation-gateF1/F2/F3.Ownership: Architecture/harness defines the matrix; scaffold/workflow makes it runnable; test writers implement tier-specific cases; reviewers verify the contract; the runner reports; seed-data owners preserve uniqueness, idempotency, realism, and accumulation integrity. Missin
…(truncated)