# PHP Workx Clai Pre Mortem > Pre-Mortem Skill - Skill: `tomevault-io/php-workx-clai-pre-mortem` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/php-workx-clai-pre-mortem` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/php-workx-clai-pre-mortem/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/php-workx-clai-pre-mortem --- # Pre-Mortem Skill > **Quick Ref:** Checklist generation -> Tooling -> Agent verification. Output: `.agents/pre-mortems/*.md` **YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.** **Architecture:** Generate explicit checklist from failure-taxonomy.md BEFORE reading spec. Tools verify what's verifiable. Agents check what requires judgment. Every finding must have location (line number) and specific fix. ## Execution Steps Given `/pre-mortem `: ### Step 1: Load the Spec/Plan If a path is provided, read it: ``` Tool: Read Parameters: file_path: ``` If no path, check for recent plans: ```bash ls -lt .agents/plans/ .agents/specs/ 2>/dev/null | head -5 ``` ### Step 1a: Search for Prior Failure Learnings (if ao available) **Before generating the checklist, search for relevant past failures:** ```bash # Search for prior failure patterns related to this topic ao search "failure " 2>/dev/null || echo "ao not available, skipping failure pattern search" # Also search for incidents and anti-patterns ao search "incident " 2>/dev/null ao anti-patterns 2>/dev/null | grep -i "" || true ``` **Review ao search results:** If ao returns relevant learnings, incorporate them: - **Prior incidents:** Add checks for conditions that caused past failures - **Known anti-patterns:** Add specific checklist items to verify they're avoided - **Lessons learned:** Use these to generate additional verification questions **Note:** This search runs BEFORE generating the checklist so prior knowledge can inform what to check. ### Step 2: Generate Explicit Checklist BEFORE Reading **Load the failure taxonomy FIRST:** ``` Tool: Read Parameters: file_path: skills/pre-mortem/references/failure-taxonomy.md ``` **For each category in the taxonomy, generate specific questions:** | Category | Checklist Item | Verification Method | |----------|----------------|---------------------| | Interface Mismatch | Does spec define API schema? | Search for `schema:` or `interface` | | Timing | Does spec define timeouts? | Search for `timeout:` | | Error Handling | Does spec define error states? | Search for `error:` or `failure:` | | Safety | Does spec require confirmation for destructive ops? | Search for `confirm` | | Integration | Does spec list dependencies? | Search for `depends:` or `requires:` | | Rollback | Does spec define rollback procedure? | Search for `rollback` or `revert` | | State | Does spec define state transitions? | Search for `state:` or `transition` | **The checklist above covers 7 essential items. For comprehensive validation, use all 10 categories from `references/failure-taxonomy.md`.** **Build the checklist BEFORE reading the spec.** This prevents pattern-matching bias. ### Step 3: Run Mechanical Cross-Reference Check **Before dispatching agents, run automated cross-reference:** ```bash ./scripts/spec-cross-reference.sh | tee .agents/pre-mortems/cross-ref.md ``` This catches mechanically: - File paths that don't exist - Function/type references that aren't defined - Broken markdown links Include output in pre-mortem report under "## Cross-Reference Verification" ### Step 3a: Run Available Tooling **If the spec references code that exists:** ```bash # If code exists, run linting ./scripts/toolchain-validate.sh --quick 2>&1 | head -30 ``` **If spec is for new code:** Skip to Step 4. ### Step 4: Verify Checklist Items **Verify checklist items systematically. Do not "simulate failures" - check for specific gaps.** #### 4a. Verify Spec Completeness For EACH checklist item from failure-taxonomy.md, read the spec and answer: | Checklist Item | Present? | Location (line) | Complete? | |----------------|----------|-----------------|-----------| | API schema defined | yes/no | line N | yes/partial/no | | Timeouts specified | yes/no | line N | yes/partial/no | | Error states listed | yes/no | line N | yes/partial/no | | Rollback procedure | yes/no | line N | yes/partial/no | | Dependencies listed | yes/no | line N | yes/partial/no | | State transitions | yes/no | line N | yes/partial/no | | Confirmation for destructive ops | yes/no | line N | yes/partial/no | For items marked "no" or "partial": flag as GAP with specific fix. #### 4b. Find Implicit Assumptions Find statements that assume something without stating it: - "The user will..." -> What if they don't? - "The API returns..." -> What if it errors? - "This runs after..." -> What if order changes? Record assumptions: | Location (line) | Assumption | What If Wrong? | Specific Clarification Needed | |-----------------|------------|----------------|-------------------------------| Every finding MUST have a line number and specific fix. #### 4c. Find Boundary Conditions For each input/parameter in the spec: | Location (line) | Input | Type | Min/Max Stated? | Empty Handling? | Invalid Handling? | |-----------------|-------|------|-----------------|-----------------|-------------------| Flag any inputs without explicit boundary handling. Every finding MUST have a line number and specific fix. ### Step 5: Categorize Findings Combine agent outputs and categorize: | Severity | Definition | Action | |----------|------------|--------| | **CRITICAL** | Spec has fundamental gap (no rollback, no error handling) | Must fix before implementation | | **HIGH** | Spec makes unstated assumptions | Should clarify | | **MEDIUM** | Spec could be clearer | Worth noting | | **LOW** | Minor improvements | Optional | **Every finding must have:** 1. Location (line number in spec) 2. Description (what's missing or unclear) 3. Specific fix (exact text to add/change) ### Apply Enhancement Patterns For each finding, identify the applicable pattern from `references/enhancement-patterns.md`: | Gap Type | Enhancement Pattern | |----------|---------------------| | Missing schema | "Schema from Code" - Extract schema from actual code | | Missing error handling | "Error Recovery Matrix" - Map all error types to actions | | Missing timeouts | "Per-Tool Timeout Configuration" - Add per-operation timeouts | | Missing safety info | "Mandatory Safety Display" - Add safety level classification | | Missing progress feedback | "Progress Feedback Specification" - Add update frequency | | Missing escalation | "Escalation Flow" - Define when/how to escalate | | Missing audit trail | "Audit Trail Requirements" - Add logging requirements | ### Step 6: Write Pre-Mortem Report **Write to:** `.agents/pre-mortems/YYYY-MM-DD-.md` ```markdown # Pre-Mortem: **Date:** YYYY-MM-DD **Spec:** ## Checklist Verification | Category | Item | Present? | Location | Complete? | |----------|------|----------|----------|-----------| | Interface | API schema | yes/no | line N | yes/no | | Timing | Timeouts | yes/no | line N | yes/no | | Error | Error states | yes/no | line N | yes/no | | Safety | Confirmation | yes/no | line N | yes/no | | Rollback | Rollback procedure | yes/no | line N | yes/no | | Deps | Dependencies listed | yes/no | line N | yes/no | | State | State transitions | yes/no | line N | yes/no | ## Findings ### CRITICAL (Must Fix Before Implementation) 1. ****: - **Location:** line N - **Why Critical:** - **Specific Fix:** ### HIGH (Should Clarify) 1. ****: - **Location:** line N - **Assumption Made:** - **Specific Clarification:** ### MEDIUM - **** (line N): ## Implicit Assumptions Found | Location | Assumption | Risk | Clarification Needed | |----------|------------|------|---------------------| ## Edge Cases Without Handling | Location | Input | Boundary Missing | Suggested Handling | |----------|-------|-----------------|-------------------| ## Verdict [ ] READY - All checklist items present, no CRITICAL gaps [ ] NEEDS WORK - CRITICAL gaps must be addressed ``` ### Step 7: Request Human Approval (Gate 3) **Gate Criteria:** - **READY**: 0 CRITICAL gaps, <=2 HIGH gaps - **NEEDS WORK**: 1+ CRITICAL or >2 HIGH gaps ``` Tool: AskUserQuestion Parameters: questions: - question: "Pre-mortem found gaps. Proceed to implementation?" header: "Gate 3" options: - label: "Proceed" description: "Gaps acceptable, start implementation" - label: "Fix Spec" description: "Address gaps before implementing" - label: "More Research" description: "Need more information" multiSelect: false ``` ### Step 8: Report to User Tell the user: 1. Checklist verification results (table) 2. Number of gaps by severity 3. Top 3 items that need attention (with line numbers) 4. Location of pre-mortem report 5. Gate 3 decision ## Key Differences from Previous Version | Before | After | |--------|-------| | "Simulate failures" (vague) | Verify checklist items (specific) | | 4 failure experts | 3 verification agents | | Gestalt impression | Explicit checklist + location (line number) | | No methodology | Uses failure-taxonomy.md | | Findings without location | Every finding has line number and specific fix | | Pattern matching | Mechanical verification | --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/php-workx) — claim your Tome and manage your conversions.