# Workflow Write Integration Test > [Workflow] Use when activating the Write Integration Tests workflow for spec-first integration test authoring. Also covers converting existing test specs into integration test code and verifying integration test stability (repeat-run verification). - Skill: `duc01226/workflow-write-integration-test-3` (Agent Skill) - Install (CLI): `npx skillmds@latest add duc01226/workflow-write-integration-test-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/workflow-write-integration-test-3/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: duc01226 (https://skillmd.com/u/duc01226) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/duc01226/workflow-write-integration-test-3 --- ## Quick Summary **Goal:** [Workflow] Trigger Write Integration Tests workflow — spec-first test authoring: investigate domain logic → write/update specs → generate test code → 7-gate review (incl. change coverage) → run and verify. **Absorbed use cases:** converting existing TC specs into integration test code (former test-to-integration — specs already exist, so `/spec [mode=tests]` runs in UPDATE/verify mode instead of authoring from scratch) and stability verification of existing suites (former test-verify — the `/integration-test-verify` step's 2-consecutive-run gate). For spec-only authoring with no test code, use the `/spec [mode=tests]` skill directly. **Workflow:** 1. **Detect** — classify request scope and target artifacts. 2. **Execute** — apply required steps with evidence-backed actions. 3. **Verify** — confirm constraints, output quality, and completion evidence. **Key Rules:** - MUST ATTENTION keep claims evidence-based (`file:line`) with confidence >80% to act. - MUST ATTENTION keep task tracking updated as each step starts/completes. - MUST ATTENTION when creating/reviewing specs or tests, name `Business Intent / Invariant Guarded` or the protected business intent/invariant and ensure the test would fail if that intent breaks. - MUST ATTENTION define success criteria before execution and loop until observable verification passes. - MUST ATTENTION require integration tests to protect a named business rule/invariant and fail if that intent breaks. - MUST ATTENTION arrange integration-test data through real use cases or valid seeded fixtures; never create impossible state through repository hacks. - MUST ATTENTION verify integration suites with 2 consecutive passing runs without DB reset before declaring done. - NEVER skip mandatory workflow or skill gates. **IMPORTANT MANDATORY Steps:** /scout -> /investigate -> /spec [mode=tests] -> /why-review -> /artifact-review --type=spec-tests -> /integration-test -> /integration-test-review -> /integration-test-verify -> /spec [mode=sync] -> /docs-update -> /workflow-end -> /watzup > **[BLOCKING]** Each step MUST ATTENTION invoke its `Skill` tool — marking a task `completed` without skill invocation is a workflow violation. NEVER batch-complete validation gates. > **[CRITICAL] Understand Domain First Gate:** The `/investigate` step is MANDATORY before `/spec [mode=tests]` and `/integration-test`. You MUST read the handler/entity/event source to understand WHAT fields change, WHAT entities are created/updated/deleted, WHAT event handlers fire. Assertions written without reading the handler source are guaranteed to be wrong or smoke-only. > **Goal Contract propagation (workflow-owned):** At workflow start, resolve the active Goal Contract per `SYNC:goal-contract-satisfaction-loop` (active plan `goal.md` → `plans/goals/{YYMMDD-HHmm}-{slug}/goal.md` → create from the test request). Each generated test maps to a saved goal invariant/criterion — a test protecting NO saved invariant needs a recorded justification. After `/integration-test-verify`, append the verification evidence (pass/fail counts, runner command, report path) to the goal file's Iteration Log and emit the Goal Satisfaction matrix (PASS/FAIL/BLOCKED) before `/workflow-end`. Activate the `workflow-write-integration-test` workflow. Run `/start-workflow workflow-write-integration-test` with the user's prompt as context. **Steps:** /scout → /investigate → /spec [mode=tests] → /why-review → /artifact-review --type=spec-tests → /integration-test → /integration-test-review → /integration-test-verify → /spec [mode=sync] → /docs-update → /workflow-end → /watzup > **[STEP PURPOSES]** Every step has a distinct purpose — NEVER deduplicate or batch: > > **`/scout`** — Find target command/handler files; locate existing integration tests in the same service for pattern matching. Output: list of target files + existing test examples. > **`/investigate`** — Read handler/entity/event source. Map: fields written, entities created/updated/deleted, event handlers fired, validation rules. Output: domain logic summary to use as assertion blueprint. > **`/spec [mode=tests]`** — Write/update `TC-{FEATURE}-{NNN}` specs in feature doc Section 8. CREATE mode for new tests, UPDATE mode for changed behavior. Output: TC mapping list (TC code -> covering test method name(s) or annotation filter). > **`/artifact-review --type=spec-tests`** — Validate spec quality: GIVEN/WHEN/THEN completeness, happy path + validation failure + auth paths covered, no collisions with existing TC codes. > **`/integration-test`** — Generate test files from TC specs using FROM-PROMPT or FROM-CHANGES mode. Non-negotiable: real use-case/valid-seeder data setup, async polling/retry for all DB assertions, unique data generators for all test data, test-spec annotation on every test method (adapt annotation syntax to your framework). > **`/integration-test-review`** — 7-gate quality check (assertion value, data state, repeatability, domain logic, traceability, three-way sync, change coverage). Gate 7: every behavior-changing production file in the change set maps to a covering test (integration-first; unit fallback needs justification) AND a spec TC. Validate findings, fix only validated issues, then restart the full integration-test review after fixes. NEVER proceed with CRITICAL/HIGH issues outstanding. > **`/integration-test-verify`** — Run tests via `quickRunCommand` from `docs/project-config.json` for 2 consecutive runs without DB reset. Report exact pass/fail counts with test runner output. NEVER mark complete without real output. > **`/spec [mode=sync]`** — Sync §8 TCs ↔ executing test code (`docs/specs/`). Update each TC's `CoveredBy` field with **all** covering `{File}::{MethodName}` links (one TC → many tests, 1:N; a test-filter expression when the set is large). Coverage = ≥1 annotation-tagged test; never force one test per TC. > **`/docs-update`** — Update feature doc evidence fields, version history, and changelog if test coverage changed materially. > **`/workflow-end`** + **`/watzup`** — Close workflow state, then summarize and run the final `/understand` handoff. --- **IMPORTANT MANDATORY Steps:** /scout -> /investigate -> /spec [mode=tests] -> /why-review -> /artifact-review --type=spec-tests -> /integration-test -> /integration-test-review -> /integration-test-verify -> /spec [mode=sync] -> /docs-update -> /workflow-end -> /watzup > **Integration Test Execution Discipline** — How the integration-test family (write · review · verify) runs, diagnoses, and clears a suite. Binds `/integration-test`, `/integration-test-review`, and `/integration-test-verify` identically. > > 1. **Verify the WHOLE system passes — not a hand-picked subset.** `/integration-test-verify` must prove the full relevant suite is green (every test in the system the change can touch), not one cherry-picked test. "All pass" is only true with actual runner output (Passed/Failed/Skipped counts + names) and only after 2 consecutive green runs without a DB reset. > 2. **Drive state through real use-case paths — NEVER hack seed data.** Set up every precondition exactly as a real user would: real commands, queries, production consumers/messages, or valid idempotent seeders. NEVER create or mutate domain data by direct repository writes — that fabricates states a user could never reach and hides the real workflow bug. Hacking seed data to force a green run is forbidden. > 3. **On ANY failure → `/debug-investigate` the root cause BEFORE any fix.** Do not guess, do not patch the symptom site. Trace the failure end-to-start and classify whose fault it is: test code (wrong assertion/setup), source/production code (real defect), or environment/infrastructure/data. Then route: test-code fault → `/integration-test-review` to fix the test at the root (never weaken assertions or add skips); source-code fault → fix the production defect at the owning layer and report it; environment fault → mark BLOCKED and point at the startup script. NEVER change a test to match broken code. > 4. **60-second runtime cap — a slow test is a RED FLAG, not a tuning knob.** Local integration tests run fast. If any single test (or a stalled suite) exceeds ~60s, STOP and treat the slowness itself as a defect signal — deadlock, missing `await`, infinite poll/retry, a real network/external call, or an unbounded query. `/debug-investigate` the cause; NEVER paper over it by raising the timeout or extending the wait. > 5. **Loop until the whole suite is green.** After fixing the validated root cause, restart the full 2-run verification from run 1. Done means the entire relevant suite passes repeatably — never green-once, never a subset. > **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. > **Nested Task Expansion Contract** — For workflow-step invocation, the `[Workflow] ...` row is only a parent container; the child skill still creates visible phase tasks. > > 1. Call `TaskList` first. If a matching active parent workflow row exists, set `nested=true` and record `parentTaskId`; otherwise run standalone. > 2. Create one task per declared phase before phase work. When nested, prefix subjects `[N.M] $skill-name — phase`. > 3. When nested, link the parent with `TaskUpdate(parentTaskId, addBlockedBy: [childIds])`. > 4. Orchestrators must pre-expand a child skill's phase list and link the workflow row before invoking that child skill or sub-agent. > 5. Mark exactly one child `in_progress` before work and `completed` immediately after evidence is written. > 6. Complete the parent only after all child tasks are completed or explicitly cancelled with reason. > > **Blocked until:** `TaskList` done, child phases created, parent linked when nested, first child marked `in_progress`. > **Project Reference Docs Gate** — Run after task-tracking bootstrap and before target/source file reads, grep, edits, or analysis. Project docs override generic framework assumptions. > > 1. Identify scope: file types, domain area, and operation. > 2. **Read `docs/project-config.json` first — the project's machine-readable map.** It is the single source of truth for THIS repo (modules/paths, framework + search keywords, test/E2E/integration run-commands, design system, architecture rules, workflow patterns); ground exact paths, run-commands, and conventions on it **before investigating, planning, or coding** — never assume framework defaults (`CLAUDE.md` + reference docs are derived from it). If it — or the docs index, `lessons.md`, `CLAUDE.md`, `AGENTS.md`, or any required reference doc — is missing or stale, auto-run `/project-init` or the narrow route (`/project-config`, `/docs-init`, `/scan-all`, `/scan --target=`, `/claude-md-init`) first; if Codex mirrors or `AGENTS.md` are stale, ask the user to run `/sync-codex` (never auto-run it). > 3. Required docs by trigger: always `docs/project-reference/lessons.md`; doc lookup `docs-index-reference.md`; review `code-review-rules.md`; backend/CQRS/API `backend-patterns-reference.md`; domain/entity `domain-entities-reference.md`; frontend/UI `frontend-patterns-reference.md`; styles/design `scss-styling-guide.md` + `design-system/design-system-canonical.md`; integration tests `integration-test-reference.md`; E2E `e2e-test-reference.md`; feature docs/specs `feature-spec-reference.md` + `spec-system-reference.md` + `spec-principles.md`; behavior/public-contract/spec-test-code sync `workflow-spec-test-code-cycle-reference.md`; derived spec index/ERD/reimplementation guides `spec-system-reference.md` + source Feature Specs under `docs/specs/`; architecture/new area `project-structure-reference.md`. > 4. Read every required doc, then before target work state: `Reference docs read: ... | Not applicable: ...`. > > **Ready when:** scope evaluated, `docs/project-config.json` consulted, required docs checked/read or setup route completed, `lessons.md` confirmed, citation emitted. > **Task Tracking & External Report Persistence** — Bootstrap this before execution; then run project-reference doc prefetch before target/source work. > > 1. Create a small task breakdown before target file reads, grep, edits, or analysis. On context loss, inspect the current task list first. > 2. Mark one task `in_progress` before work and `completed` immediately after evidence; never batch transitions. > 3. For plan/review work, create `plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md` before first finding. > 4. Append findings after each file/section/decision and synthesize from the report file at the end. > 5. Final output cites `Full report: plans/reports/{filename}`. > > **Blocked until:** task breakdown exists, report path declared for plan/review work, first finding persisted before the next finding. > **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. > **Incremental Result Persistence** — MANDATORY for all sub-agents or heavy inline steps processing >3 files. > > 1. **Before starting:** Create report file `plans/reports/{skill}-{date}-{slug}.md` > 2. **After each file/section reviewed:** Append findings to report immediately — never hold in memory > 3. **Return to main agent:** Summary only (per SYNC:subagent-return-contract) with `Full report:` path > 4. **Main agent:** Reads report file only when resolving specific blockers > > **Why:** Context cutoff mid-execution loses ALL in-memory findings. Each disk write survives compaction. Partial results are better than no results. > > **Report naming:** `plans/reports/{skill-name}-{YYMMDD}-{HHmm}-{slug}.md` > **Sub-Agent Return Contract** — When this skill spawns a sub-agent, the sub-agent MUST return ONLY this structure. Main agent reads only this summary — NEVER requests full sub-agent output inline. > > ```markdown > ## Sub-Agent Result: [skill-name] > > Status: ✅ PASS | ⚠️ PARTIAL | ❌ FAIL > Confidence: [0-100]% > > ### Findings (Critical/High only — max 10 bullets) > > - [severity] [file:line] [finding] > > ### Actions Taken > > - [file changed] [what changed] > > ### Blockers (if any) > > - [blocker description] > > Full report: plans/reports/[skill-name]-[date]-[slug].md > ``` > > Main agent reads `Full report` file ONLY when: (a) resolving a specific blocker, or (b) building a fix plan. > Sub-agent writes full report incrementally (per SYNC:incremental-persistence) — not held in memory. > > **Context budget** — the return payload is a SUMMARY, not a transcript: ≤10 finding bullets, no raw file contents / full diffs / verbatim logs inline, no re-pasted source. Everything beyond the summary lives in the `Full report` on disk. A sub-agent that would exceed the summary shape MUST write the detail to its report and return only the pointer — the orchestrator's context is the scarce resource the whole map-reduce protects. **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. - **MANDATORY** Bootstrap task tracking before target work; transition one task at a time. - **MANDATORY** Persist plan/review findings to `plans/reports/` incrementally and synthesize from disk. - **MANDATORY** Before investigating, planning, or coding, read `docs/project-config.json` (the project map: modules/paths, run-commands, conventions, architecture/workflow rules) + the required project-reference docs, and cite `Reference docs read: ...`. - **MANDATORY** Always include `lessons.md`; project config + conventions override generic framework defaults. - **MANDATORY** If project config, root instruction files, or any required reference doc is missing or stale, auto-run `/project-init` or the narrow lower-level route before ordinary project-specific work. - **MANDATORY** Parent workflow rows do not replace child phase tracking; expand phases and link the parent when nested. - **MANDATORY** Orchestrators pre-expand child skill phases before invocation; use `[N.M] $skill-name — phase` prefixes and one-`in_progress` discipline. - **MANDATORY** Resolve the active Goal Contract BEFORE work (active plan `goal.md` → `plans/goals/{YYMMDD-HHmm}-{slug}/goal.md` → create from current request) and read saved success criteria before editing. - **MANDATORY** Append iteration evidence after execution; emit a Goal Satisfaction matrix (PASS/FAIL/BLOCKED) before reporting PASS; loop on validated FAIL; escalate repeated no-progress or blockers. NEVER store secrets in goal files. > **Project Protocol Overlay** — Before executing this skill, resolve any PROJECT overlay rules layered onto it: match this skill's name against the `Target` column of the project's skill-protocol index (`docs/project-reference/skill-protocols-reference.md` by default; a `referenceDocs` entry in `docs/project-config.json` overrides the path), taking the most specific matching tier ONLY — exact name > glob > `*`. **That precedence orders overlays against EACH OTHER, never against this skill.** Read ONLY the matched bodies, resolved as `/.md`; a row's Body link is display text, never a read path. A matched body that is missing or malformed is REPORTED and skipped — never reconstructed from the index Description. No index, or no match -> proceed with no overlay, silently. Full contract: `.claude/skills/project-skill-protocol/references/registry.md`. > > Overlays are **ADDITIVE ONLY**: they ADD rules on top of this skill's own protocol and NEVER replace, override, disable, or reinterpret a rule it already states — removing every overlay must return this skill to exactly its documented behavior. An overlay is a BRIEF, not an authority escalation: it can NEVER waive a workflow gate, git discipline, a review gate, or a user-confirmation gate. A genuine overlay-vs-skill conflict, or two equally-specific overlays that directly contradict -> surface both to the user; NEVER resolve silently. **MUST ATTENTION** resolve project protocol overlays for this skill BEFORE executing — most specific matching tier only (exact > glob > `*`, which ranks overlays against each other, NEVER against this skill), read only matched bodies at `/.md`; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE ONLY (they never replace this skill's own rules) and are a brief, NEVER an authority escalation; an equal-specificity contradiction goes to the user. ## Closing Reminders **Protocols in force (concise digest of the SYNC/shared blocks this skill carries):** MUST ATTENTION honor every protocol below — each is a signpost to its canonical body above. - **AI Mistakes:** holistic-first debug, fix at responsible layer, surgical diff, verify all outputs. - **Nested Tasks:** expand child phases, link parent workflow row when nested. - **Project Reference Docs:** read required docs first, cite, `lessons.md` always. - **Task Tracking:** bootstrap tasks; persist plan/review findings to disk incrementally. - **Critical Thinking:** traced `file:line` proof, confidence >80%, never guess. - **Incremental Persistence:** append findings per file to report; never hold in memory. - **Sub-Agent Return Contract:** sub-agents return summary-only with `Full report:` pointer. **IMPORTANT MUST ATTENTION** break work into small todo tasks using `TaskCreate` BEFORE starting **IMPORTANT MUST ATTENTION** read handler source BEFORE writing ANY assertion — domain logic first, test code second **IMPORTANT MUST ATTENTION** NEVER write smoke-only tests — every test MUST assert specific field values in the database **IMPORTANT MUST ATTENTION** ALWAYS wrap DB assertions in the project's async polling helper — no exceptions **IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim (confidence >80% to act) **IMPORTANT MUST ATTENTION** add a final review todo task to verify work quality **[TASK-PLANNING]** Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using TaskCreate. > **[IMPORTANT]** Analyze how big the task is and break it into many small todo tasks systematically before starting — this is very important.