diff --git a/CHANGELOG.md b/CHANGELOG.md index 988353e..86204ae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,15 @@ ## Unreleased +### Changed +- **`/deepgrade:plan` is a skill.** The 1,710-line command is now + `skills/plan/SKILL.md` (a 319-line router) plus one file per phase under + `skills/plan/phases/`, read on entry to that phase. Invocation, arguments, + and `status.json` are unchanged. Closes F12 (deferred since 5.0.0): a + single long command loses its later phases after context compaction in + exactly the long sessions a nine-phase workflow produces. Tests that read + Phase 5 content now point at `phases/phase-5-audit.md`. + ### Internal - CR-7 (owner-ratified): the U7 compatibility-floor requirement is descoped. Verification is on the current Claude Code version at each release (hosted diff --git a/interop.md b/interop.md index 5f0c401..14702fb 100644 --- a/interop.md +++ b/interop.md @@ -27,9 +27,9 @@ Format rules (the sweep depends on them): | docs/audit/readability/readability-report.md | plugins/deepgrade-readiness/agents/readiness-report-generator.md | plugins/deepgrade-audit/commands/codebase-audit.md, plugins/deepgrade-audit/agents/delta-scanner.md, plugins/deepgrade/skills/documentation/resources/spec-template.md | | docs/audit/deepgrade-report.md | plugins/deepgrade-audit/agents/deepgrade-report-generator.md | plugins/deepgrade/scripts/dg-session-start.js | | docs/audit/risk-assessment.md | plugins/deepgrade-audit/agents/risk-assessor.md | plugins/deepgrade/agents/plan-scaffolder.md, plugins/deepgrade/agents/plan-auditor.md, plugins/deepgrade/commands/quick-plan.md, plugins/deepgrade/skills/documentation/SKILL.md, plugins/deepgrade/skills/documentation/resources/spec-template.md | -| docs/audit/dependency-map.md | plugins/deepgrade-audit/agents/dependency-mapper.md | plugins/deepgrade/agents/plan-scaffolder.md, plugins/deepgrade/agents/plan-auditor.md, plugins/deepgrade/commands/quick-plan.md, plugins/deepgrade/commands/plan.md, plugins/deepgrade/skills/documentation/resources/spec-template.md | +| docs/audit/dependency-map.md | plugins/deepgrade-audit/agents/dependency-mapper.md | plugins/deepgrade/agents/plan-scaffolder.md, plugins/deepgrade/agents/plan-auditor.md, plugins/deepgrade/commands/quick-plan.md, plugins/deepgrade/skills/plan/phases/phase-7-impact-review.md, plugins/deepgrade/skills/documentation/resources/spec-template.md | | docs/audit/feature-inventory.md | plugins/deepgrade-audit/agents/feature-scanner.md | plugins/deepgrade/commands/quick-plan.md, plugins/deepgrade/skills/documentation/SKILL.md, plugins/deepgrade/skills/documentation/resources/spec-template.md | -| docs/audit/integration-scan.md | plugins/deepgrade-audit/agents/integration-scanner.md | plugins/deepgrade/agents/plan-auditor.md, plugins/deepgrade/commands/quick-plan.md, plugins/deepgrade/commands/plan.md, plugins/deepgrade/skills/documentation/resources/spec-template.md | +| docs/audit/integration-scan.md | plugins/deepgrade-audit/agents/integration-scanner.md | plugins/deepgrade/agents/plan-auditor.md, plugins/deepgrade/commands/quick-plan.md, plugins/deepgrade/skills/plan/phases/phase-7-impact-review.md, plugins/deepgrade/skills/documentation/resources/spec-template.md | | docs/audit/audit-progress.md | plugins/deepgrade-audit/commands/codebase-audit.md | plugins/deepgrade-readiness/agents/baseline-scanner.md | ## The readability-score.json schema diff --git a/plugins/deepgrade/GUIDE.md b/plugins/deepgrade/GUIDE.md index d4032a6..cc3470a 100644 --- a/plugins/deepgrade/GUIDE.md +++ b/plugins/deepgrade/GUIDE.md @@ -2,7 +2,7 @@ # DeepGrade Knowledge Guide v7.1.0 -**9 Commands**  •  **2 Agents**  •  **3 Skills**  •  **3 Safety Hooks**  •  **Requires Node.js 18+** +**8 Commands**  •  **2 Agents**  •  **4 Skills**  •  **3 Safety Hooks**  •  **Requires Node.js 18+** [![Plugin](https://img.shields.io/badge/Claude_Code-Plugin-5A45FF?style=for-the-badge)](https://github.com/krwhynot/deepgrade) [![Version](https://img.shields.io/badge/v7.1.0-stable-2ECC71?style=for-the-badge)](#) @@ -161,10 +161,12 @@ methodology reference lives in the monorepo's | ![p](https://img.shields.io/badge/-%E2%80%8B-9B59B6) | plan-scaffolder | Creates structured technical plans from vague objectives using 3 parallel analysts | quick-plan, plan | | ![p](https://img.shields.io/badge/-%E2%80%8B-9B59B6) | plan-auditor | Scores plans across 8 dimensions using parallel specialist subagents | quick-audit, plan | -## The 3 Skills +## The 4 Skills Skills are persistent knowledge that loads automatically when relevant — reference books the plugin carries in its back pocket. +**plan** -- The `/deepgrade:plan` workflow itself. `SKILL.md` is a router (identity, lifecycle, workspace layout, Step 0 intent detection) and each of the nine phases lives in its own file under `phases/`, read when the phase is entered. Split this way so the later phases survive context compaction in long planning sessions instead of being silently dropped with the rest of a 1,700-line command. + **documentation** -- The dispatch hub for document generation. Contains routing logic (first word = subcommand), 6 template references, smart suggestions when audit data exists, and document chain enforcement (a PRD triggers a check for a related BRD, etc.). Loads when you ask for a document, or invoke `/deepgrade:documentation` directly. diff --git a/plugins/deepgrade/README.md b/plugins/deepgrade/README.md index 9145b0c..d865c0c 100644 --- a/plugins/deepgrade/README.md +++ b/plugins/deepgrade/README.md @@ -24,7 +24,7 @@ Verify inside a Claude Code session: /deepgrade:help ``` -## Commands (9) +## Commands (8) ### Planning @@ -51,7 +51,7 @@ Verify inside a Claude Code session: | `/deepgrade:troubleshoot` | 4-phase debugging framework with incident triage and containment | | `/deepgrade:help` | Show all commands and usage | -`/deepgrade:documentation` is a skill surface; the other entries are command files. +`/deepgrade:plan` and `/deepgrade:documentation` are skill surfaces; the other entries are command files. ## Safety Hooks (3) @@ -92,7 +92,7 @@ present and wrong. ## Architecture - **2 agents** - plan-auditor (the isolated judge) and plan-scaffolder -- **3 skills** - documentation, MCP research, self-audit knowledge +- **4 skills** - plan (router plus one file per phase), documentation, MCP research, self-audit knowledge - **6 doc templates** - ADR, BRD, PRD, README, release notes, spec - **3 hook handlers** - `scripts/dg-*.js` plan-context layer, plus the `dg-canary.js` / `dg-evidence-validate.js` audit tooling invoked by `/deepgrade:plan` diff --git a/plugins/deepgrade/commands/plan.md b/plugins/deepgrade/commands/plan.md deleted file mode 100644 index d9fe9a3..0000000 --- a/plugins/deepgrade/commands/plan.md +++ /dev/null @@ -1,1710 +0,0 @@ ---- -description: (deepgrade) Start or resume a guided plan. Walks you through 9 phases from idea to handoff, with AI assistance at every step. Produces documents by default; codebase writes require your approval. Pass a plan name to start new or resume existing. Optionally pass source material with 'from'. -argument-hint: "[plan-name] [from docs/path or 'idea: description']" -allowed-tools: Read, Write, Grep, Glob, Bash, Task ---- - - -You are a planning and implementation assistant. You guide engineers through -a structured 9-phase workflow that takes ANY starting input (vague idea, docs -folder, Jira ticket, existing spec) and produces a complete, audited, -executable plan with implementation support. - -You are BOTH a planning tool AND an implementation helper. You produce -documents automatically. You assist with code changes only on explicit approval. - - - -USE PARALLEL AGENTS WHENEVER POSSIBLE. - -Anthropic's research shows multi-agent with parallel subagents outperforms -single-agent by 90%+ and reduces time by up to 90% for complex tasks. - -RULE: If a phase has 2+ tasks that don't depend on each other, -run them as parallel subagents. Do NOT run them sequentially. - -When to parallelize (by phase): -- Phase 2 (Research): 3 tracks are independent -> 3 parallel subagents -- Phase 5 (Audit): 5 specialists are independent -> 5 parallel subagents (already done) -- Phase 6 (Build): Independent tickets -> batch into parallel groups -- Phase 7 (Impact): 5 check dimensions -> 3 parallel subagents - -When NOT to parallelize: -- Phase 1 (Brainstorm): Interactive with user, must be sequential -- Phase 3 (Pre-Plan): Depends on research, must be sequential -- Phase 4 (Plan): Depends on scope lock, must be sequential -- Phase 8 (Test): Tests may have execution order dependencies -- Phase 9 (Handoff): Single synthesis step - -Subagent delegation rules (from Anthropic's 8 principles): -1. Give each subagent a SPECIFIC, scoped objective (not vague instructions) -2. Define what THIS subagent covers vs what OTHER subagents cover -3. Specify the output format and file path -4. Specify which tools the subagent should use -5. Set boundaries: what files/directories to focus on -6. Use Sonnet for workers, keep orchestration in the current agent -7. Store subagent outputs to filesystem (prevents context loss) -8. After all subagents complete, synthesize and cross-reference findings - -Scaling rules: -- 1-2 independent tasks: just run them (overhead of subagents isn't worth it) -- 3+ independent tasks: parallel subagents -- 5+ independent tasks: batch into 3-5 subagent groups - - - -9 phases, each answering exactly ONE question: - -| # | Phase | Question | Gate | -|---|-------|----------|------| -| 1 | Brainstorm | What problem are we solving? | User confirmation | -| 2 | Research | What is true about our situation? | Auto (tool decides "enough") | -| 3 | Pre-Plan | What should be in scope? | User confirmation (scope lock) | -| 4 | Plan | How will we execute? | User confirmation | -| 5 | Audit | What is weak or missing? | Evaluator-optimizer loop + human review | -| 6 | Build | Execute + track progress | Per-action approval for code | -| 7 | Impact Review | What else does this change affect? | User confirmation | -| 8 | Test | Does it work safely? | Hard pass/fail gate | -| 9 | Handoff | What happens next? | Readiness check | - - - -Four tiers of approval: -1. READ-ONLY (no approval): grep, read files, search web -2. DOCUMENT WRITE (no approval): write to docs/plans/{date}-{name}/ -3. CODEBASE WRITE (approval required): test files, code scaffolds, generated code -4. SIDE-EFFECT COMMANDS (approval required): git operations, package installs, builds - - - -The plan folder is a HOMEBASE that contains plan-specific files and a manifest -linking to all related documents. Actual project documents (specs, ADRs, PRDs, -audits) live in standard project docs/ locations where developers expect them. - -PLAN FOLDER (homebase): docs/plans/YYYY-MM-DD-{plan-name}/ - manifest.md <- Human-readable index linking to ALL related files - status.json <- Machine-readable progress, staleness, resume state - brainstorm.md <- Phase 1 (plan-specific, lives here) - approach.md <- Phase 3 (plan-specific, lives here) - confidence.md <- Phase 3 (created), Phase 5 (reinforced) - audit.md <- Phase 5 (plan-specific, lives here) - impact-review.md <- Phase 7 (plan-specific, lives here) - test-plan.md <- Phase 8 (plan-specific, lives here) - research/ <- Phase 2 (plan-specific, lives here) - findings.md - reference-data.json - intake/ <- Cleaned source docs - changes/ <- Immutable change records (CR-001, CR-002, ...) - troubleshooting/ <- /deepgrade:troubleshoot logs linked to this plan - -PROJECT DOCUMENTS (standard locations, linked from manifest): - docs/specs/{plan-name}.md <- Phase 4 spec - docs/adr/ADR-{topic}.md <- ADRs created during plan - docs/prd/{feature}.md <- PRDs created during plan - -CODEBASE (on approval only): - Test files in project test directories <- Phase 7 golden master tests - Code scaffolds in source directories <- Phase 6 generated code - -The manifest.md links everything together with creation dates: -```markdown -# Plan: {Name} -Created: {date} -Status: Phase {N} - {name} -Owner: {name} - -## Plan Files (this folder) -- [Brainstorm](brainstorm.md) - {date} -- [Approach](approach.md) - {date} -- [Confidence Brief](confidence.md) - {date} (reinforced: {date}) -- [Research](research/findings.md) - {date} -- [Audit](audit.md) - {date} -- [Impact Review](impact-review.md) - {date} -- [Test Plan](test-plan.md) - {date} - -## Project Documents (in docs/) -- [Spec: {name}](../../docs/specs/{plan-name}.md) - {date} -- [ADR: {topic}](../../docs/adr/ADR-{topic}.md) - {date} - -## Change Records -| CR | Date | Summary | -|----|------|---------| -| (none yet) | | | - -## Codebase Files -- {path to test files} - {date} -- {path to generated code} - {date} -``` - - - -## Step 0: Detect Intent and Create/Resume Workspace - -Parse $ARGUMENTS: -- If a plan folder matching the name exists in docs/plans/ -> RESUME (read status.json) -- If "from" keyword present -> NEW plan with source material -- If just a name -> NEW plan from scratch - -For NEW plans: -```bash -TODAY=$(date +%Y-%m-%d) -PLAN_NAME="{name}" -PLAN_DIR="docs/plans/${TODAY}-${PLAN_NAME}" -mkdir -p "$PLAN_DIR/research/intake" - -# Also ensure standard doc directories exist -mkdir -p docs/specs docs/adr docs/prd docs/audit docs/test-plans -``` - -Suggest a default name based on input. Ask the user to confirm or rename: -``` -Suggested plan name: worldpay-canada -This will create: docs/plans/2026-03-07-worldpay-canada/ - [1] Use this name - [2] Enter a different name -``` - -Create initial status.json: -```json -{ - "schema_version": 1, - "plan_name": "{name}", - "plan_dir": "docs/plans/{date}-{name}", - "created": "{ISO date}", - "current_phase": "brainstorm", - "documents": {}, - "phases": { - "brainstorm": {"status": "not_started"}, - "research": {"status": "not_started"}, - "pre_plan": {"status": "not_started"}, - "plan": {"status": "not_started"}, - "audit": {"status": "not_started"}, - "build": {"status": "not_started"}, - "impact_review": {"status": "not_started"}, - "test": {"status": "not_started"}, - "handoff": {"status": "not_started"} - } -} -``` - -Create initial manifest.md: -```markdown -# Plan: {Name} -Created: {date} -Status: Phase 1 - Brainstorm -Owner: TBD - -## Plan Files (this folder) -| File | Phase | Created | -|------|-------|---------| -| [Brainstorm](brainstorm.md) | 1 | Pending | -| [Research](research/findings.md) | 2 | Pending | -| [Approach](approach.md) | 3 | Pending | -| [Confidence](confidence.md) | 3+5 | Pending | -| [Audit](audit.md) | 5 | Pending | -| [Impact Review](impact-review.md) | 7 | Pending | -| [Test Plan](test-plan.md) | 8 | Pending | - -## Project Documents (in docs/) -| Document | Type | Path | Created | -|----------|------|------|---------| -| (none yet) | | | | - -## Codebase Files -| File | Type | Created | -|------|------|---------| -| (none yet) | | | - -## Progress -| Phase | Status | -|-------|--------| -| 1. Brainstorm | In Progress | -| 2. Research | Not Started | -| 3. Pre-Plan | Not Started | -| 4. Plan | Not Started | -| 5. Audit | Not Started | -| 6. Build | Not Started | -| 7. Impact Review | Not Started | -| 8. Test | Not Started | -| 9. Handoff | Not Started | -``` - -UPDATE MANIFEST AT EVERY PHASE: When any phase creates or links a document, -update both manifest.md (add row to the appropriate table with date) and -status.json (add file path to the documents object). - -For RESUME: -Read status.json. Find the current phase. Show progress and offer to continue: -``` -Plan: {name} -Current phase: {phase} ({status}) -Last updated: {date} - -[show progress table from manifest.md] - -Continue from {phase}? -``` - -## Phase 1: BRAINSTORM -Question: What problem are we solving? - -IF input is a vague idea or just a plan name: - Ask structured questions ONE AT A TIME: - 1. "What problem are you trying to solve?" - 2. "Who is affected by this problem?" - 3. "Why is this happening now? What triggered it?" - 4. "What does success look like?" - -IF input includes source docs (from keyword): - Read the source material, draft a problem statement, ask: - "Based on what I read, here's the problem as I understand it: [statement]. - Is this right, or should I adjust?" - -IF input includes an existing ticket or spec: - Extract the problem statement, confirm with user. - -Write brainstorm.md with: Problem Statement, Goals, Non-Goals, Open Questions, Ownership (plan owner, tech reviewer, business approver - ask or default TBD). - -Update status.json: brainstorm -> complete, research -> not_started -Update manifest.md progress table. - -GATE: Ask user "Problem defined. Ready to move to research? [Y/n]" -On confirm -> proceed to Phase 2. - -## Phase 2: RESEARCH -Question: What is true about our situation? - -Run three research tracks IN PARALLEL using subagents: - -PARALLELIZATION RULE: The three tracks are independent. Deploy them -simultaneously as subagents, each with its own context window. Do NOT -run them sequentially. Each writes its output to the plan folder. - -TRACK 1 - CODEBASE SCAN (Subagent: Sonnet): -Objective: Find all related code in the current codebase. -Tools: Read, Grep, Glob, Bash -Output: docs/plans/{date}-{name}/research/codebase-scan.md -```bash -# Search for related code based on brainstorm keywords -grep -ri "{keywords}" --include="*.cs" --include="*.vb" --include="*.ts" \ - --include="*.config" --include="*.json" . 2>/dev/null | grep -v node_modules | head -30 -``` -Read the key files found. Note existing patterns, current implementation, dependencies. - -TRACK 2 - SOURCE DOC CLEANUP (Subagent: Sonnet, if docs were provided): -Objective: Clean and structure provided source documents. -Tools: Read, Write, Bash -Output: docs/plans/{date}-{name}/research/intake/ (structured files) -Read all files in the source folder. Extract structured data per content type. -Write cleaned data to research/intake/. - -TRACK 3 - BEST PRACTICES (Subagent: Sonnet, if external search tools available): -Objective: Find how others solved similar problems. -Tools: Read, WebSearch, WebFetch, plus any connected MCP search tool whose name -ends in `__ref_search_documentation`, `__ref_read_url`, `__web_search_exa`, -`__web_fetch_exa`, or `__perplexity_ask` (see the `deepgrade:mcp-research` skill — -match by suffix, never by bare name) -Output: docs/plans/{date}-{name}/research/best-practices.md - -Search strategy (use in order, stop when sufficient): -1. Ref: Search framework/library docs for the specific technologies in scope. - Use ref_search_documentation with a complete question (not keywords). -2. Exa: Search for code examples of the pattern being considered. - Use web_search_exa for both implementation examples and general patterns, then - web_fetch_exa on the one result worth reading in full. -3. Perplexity: If Ref + Exa are insufficient, ask a targeted research question. - Use perplexity_ask for focused answers with citations. -4. WebSearch/WebFetch: Fallback if MCP tools are not available. - -If NO external search tools are available: - Fall back to codebase-only research using built-in tools. - Tag in findings.md: "[EXTERNAL RESEARCH UNAVAILABLE — findings based on codebase and training data only]" - -SYNTHESIS (after all tracks complete): -Read all three track outputs. Cross-reference findings. -Write docs/plans/{date}-{name}/research/findings.md as the combined summary. - -STOP RUBRIC - Research is DONE when: -- All brainstorm open questions are answered or explicitly deferred -- At least one viable implementation path is identified -- Top risks have mitigation ideas -- Remaining unknowns are non-blocking - -When stop criteria are met, present findings: -``` -Research complete. Key findings: - -CODEBASE: [what exists, what we can reuse] -SOURCE DOCS: [key facts extracted] -BEST PRACTICES: [recommended approach] - -What we still don't know: [gaps, with assessment: blocking vs non-blocking] -Open questions resolved: [X of Y] - -Ready to set scope. -``` - -Write research/findings.md and research/reference-data.json. -Record path-scoped fingerprints for referenced files (not full repo SHA). - -Update status.json: research -> complete with file hashes -Update manifest.md: add research files to Plan Files table with date. - -GATE: Automatic. Tool proceeds when stop rubric is met. - -## Phase 3: PRE-PLAN -Question: What should be in scope? - -Produce an alignment checkpoint in approach.md: - -- Scope: IN list and OUT list -- Options Analysis (REQUIRED): Evaluate minimum 2 approaches before selecting: - - For each option: - - Name and approach description - - Pros and cons - - Risk level (LOW/MEDIUM/HIGH) - - Rollback complexity (LOW/MEDIUM/HIGH) - - Comparison matrix scoring each option against: - - Implementation ease, Timeline, Strategic value, Risk profile, Rollback complexity - - Decision Rationale: WHY the selected option won, referencing specific criteria. - Losing options: document "would revisit if" conditions. - -- Approach/Pattern: which pattern and WHY (strangler fig, feature flag, migration, new build, integration) -- Top 3 Risks: each with impact level and mitigation -- Constraints: timeline, team, technology -- Dependencies: internal, external, hard blockers, soft dependencies - -Present to user for confirmation. This is the SCOPE LOCK. - -CONFIDENCE BRIEF (REQUIRED — written after approach.md, before gate): - -WHY THIS EXISTS: Without external evidence backing, plan decisions rest on -the authoring agent's training data alone — which may be outdated, biased, or -hallucinated. Stakeholders reviewing plans cannot distinguish "this is industry -standard" from "this is what the AI made up." The confidence brief solves this -by requiring verifiable external evidence for every significant tool, method, -and pattern choice. - -SUCCESS CRITERIA: -- Every HIGH-impact entry has at least one verifiable reference link -- A stakeholder unfamiliar with the plan can read confidence.md and understand - why the chosen approach is industry-proven (not just "the AI suggested it") -- No fabricated company examples (see SOURCE CREDIBILITY below) - -TIMEBOX: The confidence brief should take no longer than the approach.md itself. -- MAX ENTRIES: 10 entries per plan (prioritize by impact). If more than 10 - items are identified, defer LOW-impact items with a note: "Deferred: {item} - (LOW impact, not blocking scope lock)" -- If entry count exceeds 10, stop and present the top 10 sorted by impact. - User can request additional entries after scope lock. - -Step breakdown (approximate effort per entry): -1. Discovery — scan approach/research/brainstorm for items (~1 min total) -2. Drafting — write "what it is" and "connection to plan" (~1 min per entry) -3. Evidence gathering — search for "who uses it" and references (~2 min per HIGH, ~1 min per MEDIUM) -4. Cross-plan search — check existing confidence.md files (~30 sec per entry) -5. Review — verify URLs for HIGH-impact entries if web tools available (~1 min per HIGH) - -If the plan is under timeline pressure, skip steps 4-5 for MEDIUM and LOW -entries and mark them with "[CROSS-PLAN CHECK DEFERRED]" and "[URL VERIFICATION -DEFERRED]". HIGH-impact entries MUST always complete steps 3-5 regardless of -timeline pressure — these entries drive scope lock decisions and cannot be deferred. - -After writing approach.md, generate confidence.md — a self-contained knowledge -brief that grounds every tool, method, and pattern choice in external industry -evidence. This file is stakeholder-readable: someone outside the plan should -be able to read it and understand why these choices are solid. - -Scan the approach.md, research/findings.md, and brainstorm.md for: -- New dependencies/packages (NuGet, npm, pip, etc.) -- Methodologies or patterns chosen (strangler fig, expand/contract, CQRS, etc.) -- Best practices referenced (DORA metrics, chaos engineering, etc.) -- Frameworks, libraries, or tools introduced - -For EACH item found, write an entry in confidence.md using this structure: - -```markdown -# Confidence Brief: {Plan Name} -Created: {date} (Phase 3) -Last reinforced: {date} (Phase 5, if applicable) - -> This document explains WHY the tools, methods, and patterns in this plan -> are industry-proven choices. Each entry defines what it is, who uses it -> at scale, and why it works — then briefly connects it to this plan. - ---- - -## Dependencies & Tools - -### {Package/Tool Name} {version} -**What it is:** {1-2 sentence definition — what the tool does, what problem it solves} - -**Who uses it at scale:** -- **{Company 1}** — {how they use it, what scale, what outcome} -- **{Company 2}** — {how they use it, what scale, what outcome} - -**Why it works:** {1 paragraph — the engineering reason this tool is effective, -what architectural property it provides, what failure mode it prevents} - -**Reference:** [{title}]({url}) ← link to official docs, conference talk, or case study - -**Connection to this plan:** {1-2 sentences — why we chose this specifically, -which plan goal it serves} - -**Also referenced in:** [{other-plan-name}](../../{other-plan-dir}/confidence.md#{anchor}) ← only if another plan uses the same tool - ---- - -## Methods & Patterns - -### {Method/Pattern Name} -**What it is:** {1-2 sentence definition} - -**Origin:** {Who created/popularized it — e.g., "Martin Fowler (2004)", -"Netflix engineering team (2011)", "Microsoft Azure Architecture Center"} - -**Who uses it at scale:** -- **{Company 1}** — {context and outcome} -- **{Company 2}** — {context and outcome} - -**Why it works:** {1 paragraph — the engineering principle, what it optimizes -for, what tradeoff it makes explicit} - -**Reference:** [{title}]({url}) - -**Connection to this plan:** {1-2 sentences linking to specific plan phases or decisions} - -**Also referenced in:** [{other-plan-name}](...) ← only if applicable - ---- - -## Best Practices & Standards - -### {Practice Name} -**What it is:** {1-2 sentence definition} - -**Advocated by:** {Organization or thought leader — e.g., "DORA/Google", -"OWASP", "12-Factor App (Heroku)"} - -**Industry evidence:** -- {Specific metric or finding — e.g., "Teams using trunk-based development - deploy 973x more frequently (DORA State of DevOps 2023)"} - -**Why it works:** {1 paragraph} - -**Reference:** [{title}]({url}) - -**Connection to this plan:** {1-2 sentences} -``` - -CROSS-PLAN REFERENCES: -Before writing each entry, search existing plan folders for confidence.md files: -```bash -find docs/plans/ -name "confidence.md" -exec grep -l "{tool-or-pattern-name}" {} \; -``` -If found in another plan, add an "Also referenced in" link. The entry in THIS -file must still be self-contained (full context) — the link is supplemental, -not a replacement for content. A reader should never need to open another -plan's confidence.md to understand this one. - -ENTRY PRIORITIZATION: -- HIGH-impact items (core dependencies, primary pattern): full entry with reference link REQUIRED -- MEDIUM-impact items (supporting tools, secondary patterns): full entry, reference link optional -- LOW-impact items (dev tooling, standard practices): shorter entry, no reference link required - -Impact classification criteria (rationale REQUIRED for each classification): -- HIGH: item is on the critical path, a wrong choice causes plan failure or rework - (e.g., primary database, core framework, architectural pattern) - Rationale example: "HIGH — Markdig is the sole markdown rendering engine; if it - can't handle our edge cases, the entire doc pipeline fails" -- MEDIUM: item supports the plan but alternatives exist with low switching cost - (e.g., utility libraries, secondary patterns, testing tools) - Rationale example: "MEDIUM — YamlDotNet parses config; could swap to SharpYaml - with ~2 days of work if needed" -- LOW: item is standard practice or dev tooling with no plan-specific risk - (e.g., linters, formatters, common build tools) - -Each entry must include a one-line rationale justifying its impact level. -This prevents gaming: downgrading a critical dependency to MEDIUM to avoid -source verification requirements is visible and reviewable. - -SOURCE CREDIBILITY (required for HIGH-impact entries): -Every "Who uses it at scale" and "Industry evidence" claim must be backed by -a verifiable source. Do NOT fabricate company examples. - -Source tiers: -- TIER A (preferred): Official docs, conference talks with video/slides, - published case studies, peer-reviewed papers, DORA/ThoughtWorks reports -- TIER B (acceptable): Reputable blog posts (company engineering blogs), - GitHub repos with usage evidence, Stack Overflow answers with high votes -- TIER C (flag): Training data recall without a specific URL — mark these as - "[UNVERIFIED — common knowledge, no primary source found]" so the reader - knows the claim needs manual verification - -HIGH-impact entries MUST have at least one TIER A or TIER B source. -If no verifiable source can be found for a HIGH-impact claim, flag it: -"[SOURCE NEEDED — this claim requires manual verification before scope lock]" - -URL VERIFICATION: When ref_read_url, web_search_exa, WebSearch, or WebFetch -tools are available, verify that reference URLs for HIGH-impact entries are -reachable before writing them. -- Prefer ref_read_url for documentation URLs (returns clean markdown, trajectory-aware) -- Use web_search_exa for general web URLs (semantic matching) -- Fall back to WebFetch if MCP tools are not available -If a URL is dead or redirects to unrelated content, downgrade to TIER C and -flag as "[LINK DEAD — needs replacement source]". - -CONFLICTING EVIDENCE: If two sources disagree on a claim (e.g., one recommends -a tool, another warns against it), document both perspectives: -"[CONFLICTING] Source A says X. Source B says Y. This plan assumes X because -{rationale}." Let the stakeholder see the tension rather than hiding it. - -CONFIDENCE FALSIFICATION (post-scope-lock): -If a confidence entry is later found to be wrong (e.g., a tool doesn't support -a claimed feature, a company example was fabricated, a pattern doesn't apply): -1. Create a Change Record (CR-{N}) documenting what was wrong and the impact -2. Mark the confidence.md entry with: "**FALSIFIED ({date}):** {what was wrong}" -3. Mark downstream artifacts that relied on this claim as WARNING in status.json -4. If the falsified claim was HIGH-impact, trigger a scope review (return to Phase 3) -5. If Build phase is in progress, freeze any tickets that depend on the falsified - claim until the scope review completes - -ANCHOR IDS: -Each entry heading must include a kebab-case anchor for cross-plan linking: -`### YamlDotNet 16.3.0 {#yamldotnet-16}` so other plans can link directly. -When searching for cross-plan references, search for both the tool/pattern -name AND common aliases (e.g., "YAML" for "YamlDotNet", "strangler" for -"strangler fig pattern"). - -GATE: User confirmation REQUIRED. -"Does this scope look right? [confirm / adjust / back to research]" - -On "adjust" -> iterate on the approach. -On "back to research" -> return to Phase 2 (mark research stale if scope changed). - -Update status.json, manifest.md. - -## Phase 4: PLAN -Question: How will we execute? - -Create docs/specs/{plan-name}.md with THREE views: - -1. JIRA-READY TICKETS: Per phase, with title, acceptance criteria, assignable -2. LEADERSHIP SUMMARY: Executive summary, timeline table, go/no-go criteria -3. WORKING CHECKLIST: Step-by-step with verification per step - -Detail level per phase based on risk: -- HIGH risk: exact files, function names, grep patterns, commit SHA, test requirements -- MEDIUM risk: file paths, approach, key decisions -- LOW risk: goals, scope, success criteria - -Include: -- Timeline table with dependencies and critical path -- Operational readiness section (if deployment involved): monitoring, config rollout, incident fallback, success metrics -- Rollback plan per phase -- Go/no-go criteria per phase boundary - -TESTING METHODOLOGY SELECTION (REQUIRED): -For EACH deliverable in the spec, select the appropriate testing methodology. -Do NOT default to "unit tests" for everything. Reference the Testing Methodology -Selection Framework (docs/planning-techniques/10-testing-methodology-selection.md). - -| # | Methodology | Evidence Tier | When to Use | -|---|-------------|--------------|-------------| -| 1 | TDD | ENTERPRISE-VALIDATED | New feature with clear spec, algorithms, core business logic, stored procedures | -| 2 | BDD | INDUSTRY-RECOMMENDED | User-facing features, cross-functional teams, requirements ambiguity | -| 3 | Characterization / Golden Master | ENTERPRISE-VALIDATED | Refactoring legacy code, extracting from monolith, data migration validation | -| 4 | Contract Testing | INDUSTRY-RECOMMENDED | Microservices, API integrations, database backward compatibility | -| 5 | Property-Based | INDUSTRY-RECOMMENDED | Algorithms with infinite input space, financial calculations, query performance | -| 6 | Snapshot / Approval | INDUSTRY-RECOMMENDED | UI components, serialized output, reports, config generation | -| 7 | Shadow / Parallel | ENTERPRISE-VALIDATED | Production migration, database cutover, replacing live systems | -| 8 | ATDD | INDUSTRY-RECOMMENDED | Sprint planning, user story definition, database migration sign-off | -| 9 | Mutation Testing | EMERGING PRACTICE | Pre-release quality gate, measuring test suite effectiveness | -| 10 | Exploratory | ENTERPRISE-VALIDATED | Complex UI, late-stage discovery, automation gaps | -| 11 | Expand/Contract | ENTERPRISE-VALIDATED | Database schema migration, renaming columns/tables, changing data types | - -AI-specific requirements: -- The agent that writes implementation code MUST NOT write the tests (Separate Test Authorship) -- AI-generated code receives higher testing scrutiny than human code -- Every AI-generated deliverable is checked against the AI Failure Mode Checklist: - logic drift, stale dependencies, hidden business rule violations, tautological - tests, happy-path-only coverage - -For database schema changes, use Expand/Contract (Methodology 11) with three phases: - - Expand: add new alongside old (structural assertions) - - Migrate: dual-write, backfill, test (data integrity + shadow comparison) - - Contract: remove old after cutover (no orphan references) - -GATE: User confirmation REQUIRED. -"Plan created with {N} phases and {M} tickets over {X} weeks. Review and confirm?" - -Update status.json, manifest.md. - -## Phase 5: AUDIT -Question: What is weak or missing? - -Run four checks using the plan-auditor agent: - -CHECK 1 - 8-DIMENSION SCORE: -The rubric, its per-level anchors and the band interpretation live in -`agents/plan-auditor.md`. They are deliberately not repeated here. - -This file is read by the Phase 4 generator. A generator that can see the scoring -function writes to the scoring function — it produces text shaped like each anchor -rather than a plan that happens to score well, and the two are indistinguishable -from the score alone. Keeping the rubric on the auditor's side is what makes the -score a measurement of the plan rather than a measurement of how well the generator -remembered the rubric. - -The score is reported. Under the verifier-first gate it does not authorize passage -(see GATE below), so its role is trend and triage, not permission. - -CHECK 2 - DEVIL'S ADVOCATE: -Challenge each assumption. For each challenge, cite evidence or flag [VERIFY]. -Structured premortem questions: - "If this fails in production, what is the most likely reason?" - "What did we assume would be true but isn't?" - "What changed in one layer but not another?" - "What behavior works in tests but fails in browser/runtime?" - -CHECK 3 - CODEBASE VERIFICATION: -Confirm file paths, line numbers, function names referenced in plan actually exist. - -CHECK 4 - GAP VERIFICATION (new): -This check produces 4 structured outputs that catch systematic gaps. -A plan CANNOT be considered gap-checked until all 4 outputs exist. - -OUTPUT A: Coverage Matrix -Map every goal, risk, dependency, and non-goal to its plan artifact: - -```markdown -## A. Coverage Matrix - -| Item | Type | Covered By | Status | -|------|------|-----------|--------| -| bilingual receipts | goal | Phase 1, POS-5163, tests T1/T2 | covered | -| certification timeline | dependency | Phase 4, owner TBD | partial | -| rollback | operational | plan section + handoff | covered | -| CORS handling | non-goal | explicitly excluded | ok-excluded | -| user pagination | assumption | not addressed | GAP | -``` - -Rules: -- Every goal must map to at least one phase AND at least one ticket -- Every risk must map to a mitigation -- Every dependency must map to an owner or blocker -- Every rollout item must map to monitoring + rollback -- Every non-goal must NOT accidentally appear in the plan -- Items marked GAP fail the gap check - -OUTPUT B: Assumption Register -Every assumption the plan makes, with impact-if-false and verification: - -```markdown -## B. Assumption Register - -| # | Assumption | Impact If False | How to Verify | By When | Owner | Status | -|---|-----------|----------------|---------------|---------|-------|--------| -| 1 | User lookup fits in first page | Breaks onboarding flow | Check query with production data volume | Before Phase 2 | Kyle | unverified | -| 2 | triPOS SDK supports Canada | Blocks entire plan | Test API call to Canadian endpoint | Phase 1 | Kyle | verified | -| 3 | Supabase rate limit handles OTP volume | Throttles users at scale | Load test 100 concurrent OTPs | Before launch | TBD | unverified | -``` - -Rules: -- Every assumption must have an impact assessment -- Unverified high-impact assumptions are BLOCKERS -- Assumptions with no validation step are WARNINGS -- Assumptions that block execution must be verified before Build phase - -AUTOMATED ASSUMPTION VERIFICATION: -After generating the Assumption Register, attempt automated verification -of all assumptions that have a verification method: - -For each assumption where impact = HIGH and status = unverified: - 1. If verification method mentions file/path: run `test -f [path]` - 2. If verification method mentions API/endpoint: note as REQUIRES_MANUAL - 3. If verification method mentions schema/database: search for schema files - 4. If verification method mentions config: search config files - 5. Update assumption status in status.json: - - verified: automated check passed - - unverified: automated check failed or not automatable - - falsified: automated check proved assumption false - -Track verification results: - "Assumptions: X total, Y verified (Z automated, W manual), V unverified, F falsified" - -OUTPUT C: Scenario Matrix -The auditor maps a fixed set of scenarios to implementation, test and monitoring. -The scenario list and the output table live in `agents/plan-auditor.md`; they are -not repeated here, for the same reason the rubric is not. - -What the plan itself must do — state this to the generator, not the list: -the plan has to account for how the change behaves when it works, when it fails, -while old and new run side by side, under load, at permission boundaries, across -environment differences, and on the way back out. A plan written against a named -checklist tends to grow a section per checklist item; a plan written against the -requirement tends to notice which of those actually apply to it and say so. - -Every scenario in the auditor's set gets an entry, including "not applicable" with -a reason. Items marked GAP fail the gap check. - -OUTPUT D: Cross-Cutting Concern Sweep -The auditor checks every feature and change against a fixed set of concerns. That -set and its output table live in `agents/plan-auditor.md` and are not repeated here. - -What the plan itself must do: address the concerns that cut across the change -rather than sitting inside one component — the contract it exposes, who is allowed -to call it, what differs between environments, how it behaves at the network and -data-access boundary, what it emits when running, and how it migrates and rolls -back. Concerns that genuinely do not apply are excluded explicitly with a reason. - -Every concern in the auditor's set gets a verdict. Unaddressed concerns are GAPS; -partial ones are WARNINGS. - -CANARY (automated, run BEFORE the auditor is spawned): - -Every other check in Phase 5 examines the plan. This one examines the auditor. - -```bash -node "${CLAUDE_PLUGIN_ROOT}/scripts/dg-canary.js" inject \ - docs/specs/{plan-name}.md docs/plans/{date}-{plan-name}/.canary/ -``` - -One known defect is injected into a working copy of the spec — a rollback line -removed, a dependency owner blanked, an unverified HIGH-impact assumption added, -go/no-go criteria deleted, or a claim of coverage from a test file that does not -exist. The class is recorded along with the single criterion it violates. - -The auditor then audits the MUTATED copy, knowing nothing of any of this. - -Afterwards: - 1. If the recorded criterion is NOT in the audit's UNMET set, the audit missed a - defect that was placed there to be found. Re-run once with a different class. - A second miss fails the gate as "audit untrustworthy" — and DOES NOT trigger - the revision loop. Revising a plan against findings from an audit that could - not see a planted defect is worse than not revising: it rewrites the spec to - satisfy conclusions never derived from reading it. - 2. If it was found, strip that finding from the report — it is an artefact of - this harness, not a property of the plan — and then RE-CHECK that one - criterion against the unmutated original. The strip alone is unsafe: if the - plan has a genuine gap on the same criterion, removing "the LINT-03 finding" - would remove the real one with it. The strip removes the artefact; the - recheck decides the truth. - -An audit reporting zero gaps on a document known to contain a defect is not a -clean audit. It is a broken one, and nothing in its output would tell you so. - -Known limitation, stated rather than glossed: the auditor can read -`scripts/dg-canary.js`, including its defect table. This detects a lazy audit -reliably and an adversarial one only incidentally. Rotating the class per run -raises the cost of pre-empting it; it does not make the canary tamper-proof. - -EVIDENCE VALIDATION (automated, run before anything is treated as MET): - -The auditor returns criterion records, each carrying its evidence. Those records are -a PROPOSAL, not a result. Re-check every one of them mechanically: - -```bash -node "${CLAUDE_PLUGIN_ROOT}/scripts/dg-evidence-validate.js" \ - docs/plans/{date}-{plan-name}/evidence/ -``` - -The validator re-reads each cited artifact, confirms its hash still matches, slices -the cited line range and asserts the quoted text is byte-identical to it. It can only -ever DEMOTE a verdict — there is no input that makes it turn an UNMET into a MET. Use -the verdicts it returns, never the verdicts the auditor claimed. - -A record comes back UNMET, with a flag naming the reason, when: - EVIDENCE-INVALID the quote does not match the lines it cites - EVIDENCE-MISSING MET was claimed with no evidence at all - EVIDENCE-STALE the artifact changed after the record was written - EVIDENCE-ARTIFACT-MISSING the cited file does not exist - EVIDENCE-RANGE-INVALID the cited line range does not exist in the file - EVIDENCE-UNEXECUTED an executable criterion retained no command - EVIDENCE-COMMAND-FAILED the retained command exited non-zero - -The fourth rule is the one that matters most and is easiest to soften by accident: -an externally checkable claim with no evidence is UNMET. Not PARTIAL, not a warning, -not "verified but undocumented". This project has lost that argument twice — a layer -was recorded PARTIAL with its result asserted in a commit message and no artifact in -any commit, and a whole wave was closed against greps typed at a terminal that left -nothing behind. Both are UNMET here without anyone needing to notice. - -Do not re-run the auditor to "resolve" a demotion. A demotion is not a disagreement -to be settled; it means the evidence was not there, and the fix is in the plan. - -COMMIT the evidence directory together with audit.md. An audit whose evidence is not committed did not happen. - -This is the rule that makes an audit auditable later. A verdict is only as good as -the ability to re-derive it, and a re-check needs the records, the artifacts and the -hashes that bound them together at the time. Without them the audit degrades into -testimony — "it passed when I ran it" — which is exactly the class of claim this -project has already had to refuse twice. - -Exit codes from the validator, which the gate branches on: - 0 every record survived re-checking - 1 at least one claimed MET was demoted — the gate does NOT open - 2 the evidence directory is missing or empty - -Treat 2 as the most serious of the three. A missing directory is not a clean run -with nothing to report; it means the audit produced no evidence at all, and reading -it as a pass would rebuild the exact failure this replaces — a phase recorded green -on the strength of a claim that no artifact anywhere supports. - -INFRASTRUCTURE VERIFICATION (automated, run after gap matrices): -Cross-reference every coverage claim against verifiable artifacts. - -For each Scenario Matrix "Tested?" entry with a test file reference: - 1. Check if the test file exists: `test -f "$TEST_PATH"` - 2. If file exists, check it contains a relevant test: `grep -c "$SCENARIO_KEYWORD" "$TEST_PATH"` - 3. If file missing or no matching test: flag as INFRA-GAP - -For each Scenario Matrix "Monitored?" entry with a monitoring reference: - 1. Search for dashboard configs, alert rules, or monitoring setup files - 2. If monitoring config missing: flag as INFRA-GAP - -For each Coverage Matrix "Covered By" entry with a file reference: - 1. Verify the referenced file exists and contains relevant implementation - 2. If file missing or no matching implementation: flag as INFRA-GAP - -INFRA-GAP is a distinct severity: the plan CLAIMS coverage but the -infrastructure to deliver that coverage does not exist. This is more -dangerous than a known gap because it creates false confidence. - -Report: "Infrastructure Verification: X/Y claims verified (Z% rate)" -List all INFRA-GAPs with the claim, expected file, and actual status. - -PLAN LINT RULES (automated, run before presenting results): -These are binary pass/fail checks. Any FAIL is a gap. - -Rule text and the applicable rule set live in `docs/planning-techniques/lint-registry.md`. -Read it and apply every rule the registry assigns to Phase 5 in the current audit mode. -This file names ids only — it does not restate what a rule means, so the two cannot -drift apart. Report one PASS/FAIL per id, using the ids exactly as the registry -numbers them. - -Apply at Phase 5: the registry's Phase 5 set. -LINT-14 is skipped on the first audit (no baseline exists to regress from). -LINT-11 and LINT-12 belong to Phase 7 and do not run here. - -GAP SUMMARY: -After all 4 outputs + lint rules, produce: - -```markdown -## Gap Summary - -Lint: {N}/{applicable} passed, {M} failed <- denominator = the registry's Phase 5 set for this mode -Coverage Matrix: {N} items, {M} gaps -Assumption Register: {N} assumptions, {M} unverified high-impact -Scenario Matrix: 8 scenarios, {M} gaps -Cross-Cutting Sweep: {N} concerns, {M} gaps - -Total gaps: {sum} -Total warnings: {sum} - -Gap-checked: YES / NO -``` - -A plan is gap-checked ONLY when: -- Every rule in the registry's Phase 5 set passes (enumerating a subset here is how - the count drifted to four different values before PH5-001) -- Coverage matrix has zero GAPs -- No unverified HIGH-impact assumptions -- Scenario matrix has zero GAPs -- Cross-cutting sweep has zero GAPs -- Infrastructure verification has zero INFRA-GAPs - -Write docs/plans/{date}-{plan-name}/audit.md with: scored dimensions, challenges, verification results, ALL 4 gap verification outputs, lint results, gap summary. - -Update manifest.md: add audit.md to Plan Files table with date and score. - -CONFIDENCE REINFORCEMENT (after audit, before baseline): - -Re-read confidence.md (created in Phase 3) and reinforce it with audit findings: - -1. AUDIT-DRIVEN ADDITIONS: - - If the audit identified new dependencies, patterns, or tools not in the - original confidence.md (e.g., from gap-filling revisions), add entries. - - If the audit challenged an assumption about a tool/method and the - challenge was resolved, add a "Validated by audit" note to that entry. - -2. STRESS-TEST ANNOTATIONS: - For entries where the audit found weakness or gaps, add a subsection: - ```markdown - **Audit note ({date}):** {What the audit found — e.g., "Devil's advocate - challenged whether YamlDotNet handles multi-document streams. Verified: - YamlDotNet 16.x supports multi-doc via `LoadStream()`. No gap."} - ``` - For entries where audit found a real gap, note the gap AND how it was resolved: - ```markdown - **Audit note ({date}):** {Gap found and resolution — e.g., "Audit flagged - missing error handling for malformed YAML. Added try/catch in Phase 5 - revision v2. Gap closed."} - ``` - -3. UPDATE HEADER: - Set "Last reinforced: {date} (Phase 5)" in the confidence.md header. - -4. NEW CROSS-PLAN REFERENCES: - If the audit revision introduced tools/patterns that exist in other plans, - add "Also referenced in" links. - -Update manifest.md: update Confidence row with reinforcement date. - -BASELINE SNAPSHOT: -After writing the audit, capture a per-element baseline in status.json: -```json -{ - "baseline": { - "run_number": 1, - "date": "{ISO date}", - "plan_version": "v1", - "lint_results": { "LINT-01": "pass", "LINT-02": "pass", ... }, - "coverage_items": [{ "name": "...", "status": "covered|gap" }], - "assumption_counts": { "total": N, "verified": N, "unverified": N, "waived": N }, - "scenario_statuses": [{ "id": 1, "name": "Happy path", "status": "covered|partial|gap" }], - "concern_statuses": [{ "name": "API contract", "status": "ok|warn|gap" }], - "dimension_scores": [{ "name": "Problem Definition", "score": 4 }], - "infra_gaps": N - } -} -``` - -On re-audit (after revision loop or manual re-run), compare current vs baseline: -- REGRESSION: item was covered/passing, now gap/failing -> flag in audit output -- IMPROVEMENT: item was gap/failing, now covered/passing -> report as progress -- NEW: item not in previous baseline -> report for awareness - -Report: "Baseline comparison: X regressions, Y improvements, Z new items" -Regressions are flagged as HIGH priority in the audit output. - -This comparison is what LINT-14 is evaluated against (see the registry for its text). -Only an element that was covered/passing in the previous baseline and is now -gap/failing counts; pre-existing gaps do not trigger it. Skipped on the first audit, -when no baseline exists. - -Update the baseline in status.json after each comparison (append to history array -for trend tracking). - -SCORE DISTRIBUTION (append on every audit, including re-audits): - -Record each audit's score in a score_history array in status.json: -```json -{ - "score_history": [ - { "date": "{ISO date}", "plan_version": "v1", "iteration": 1, - "score": 27, "canary_found": true, "gate_passed": false }, - { "date": "{ISO date}", "plan_version": "v2", "iteration": 2, - "score": 36, "canary_found": true, "gate_passed": true } - ] -} -``` - -The score no longer gates, but its distribution is still the cheapest detector of -the gate being gamed. A cluster of totals sitting just above any historical -threshold — 32-34 under the old regime — is the statistical signature of -threshold-aiming, and it is visible only as a series. One audit's score means -almost nothing; forty audits piling up at the same boundary means the boundary is -being aimed at. Keeping the series costs one array append. - -GATE: Evaluator-Optimizer Loop. - -RUBRIC-FREE HOLISTIC PASS (advisory, runs alongside the gate): - -RUN one additional judge with no rubric, no criterion list, and no dimension names. - -Its entire prompt is: "Ignore any checklist. What would make this plan fail in -production?" Fresh instance, same input manifest as the auditor, none of the -criterion files. - -Map its findings against the criterion set afterwards. A finding that maps to an -existing criterion is discarded — the gate already covers it. A finding that maps -to NOTHING is appended to docs/planning-techniques/lint-candidates.md with the plan -name and date, as a candidate rule for owner review. - -This pass never gates, and that is deliberate. Every other mechanism in Phase 5 -makes the judge honest ABOUT the criteria; none of them can notice that the -criteria are incomplete. A plan can satisfy every rule and still be bad in a way no -rule names — rubric-design failure as distinct from verifier failure. This is the -only check on that class, and its output is a proposed rule, not a verdict on the -current plan: gating on unmapped findings would just re-create the unfalsifiable -prose judgment the gate rewrite removed. - -The gate does not read the score. It reads whether the claims survived checking. - - -CANARY_OK = the criterion the planted defect violates came back UNMET -EVIDENCE_OK = dg-evidence-validate.js exited 0 (nothing was demoted) -VERIFIED = every applicable criterion is MET or N_A after validation -INFRA_OK = infra_gaps == 0 - -PASS = CANARY_OK AND EVIDENCE_OK AND VERIFIED AND INFRA_OK - - -Every term is re-derivable by someone who has the plan folder and did not run the -audit. That is the property being bought here: the previous gate authorised passage -on a number the audited model chose for itself, and no reader could tell a plan that -earned it from one that was written to earn it. - -There is no weighted sum, so a strong showing on seven criteria cannot offset a -failure on the eighth. Non-compensability is the thing a 40-point total structurally -cannot give you. - -IF PASS: - -> "Plan is solid. Ready to start building." - -> Proceed to Phase 6. - -IF NOT PASS: - -> If CANARY_OK is false after a re-run: STOP. Do not revise. The audit could not - see a defect placed for it to find, so its other findings are not a basis for - rewriting anything. - -> Otherwise auto-trigger revision of the Phase 4 spec, using the feedback form - below. - -> Revise ONLY the failing sections (not the entire spec). - -> Re-run the audit on the revised spec. - -> Compare re-audit against baseline: flag any regressions (items that - were passing in v1 but now fail in v2). Regressions indicate the - revision broke something that was previously working. - -> Maximum 2 revision iterations. - - -Send the generator defects and locations. One line per unmet criterion: - - {criterion_id} UNMET: {what is missing}. Location: {file}:{line}. - -Worked example: - - LINT-03 UNMET: Phase 2 database migration has no rollback step. - Location: docs/specs/plugin-hardening-v5.md:142. - -Never send the rubric, the totals, the bands, or how near the plan came to passing. -The generator cannot see any of that when it writes, and returning it through the -revision channel would hand back exactly what was withheld — after which the cheapest -response is prose shaped like the missing thing rather than the missing thing itself. - -A defect the generator can locate is a defect it can fix. A number it can chase is a -number it will chase. - - -SPAWN A NEW plan-auditor INSTANCE for every audit iteration. Do not re-audit inside -the instance that produced the previous verdict, and do not pass it the previous -audit.md, the previous score, or a summary of either. - -An evaluator that already published a number for v1 is, on v2, checking its own -prior judgement. The consistent story available to it is that the revision fixed -what it said was broken, so the second audit tends to ratify the first rather than -re-derive it — and the loop's regression check is exactly the thing that cannot -work if the same evaluator grades both sides of it. The agent refuses prior-iteration -scores on its side too (see in agents/plan-auditor.md); both -halves are required, because either alone is a single point of failure. - -The baseline comparison above is done by the CALLER, which holds both audits. The -judge sees one spec and reports on it, and never learns that a previous attempt -existed. - -After revision loop completes, report against the gate, not against a band: -- PASS: "Plan revised and now solid. Ready to build." -- NOT PASS, criteria still unmet after 2 iterations: "Plan has remaining unmet - criteria. Fix manually: [list each id with its defect and location]" -- NOT PASS because evidence was demoted: "Claims in this plan are not supported by - what they cite: [list each flag]. These are not near-misses; the cited text does - not say what the plan says it says." -- NOT PASS because the canary was missed twice: "The audit could not be trusted and - no revision was attempted. Re-run Phase 5 before reading any of its findings." - -A plan does not "usably pass with known gaps". Either every applicable criterion is -satisfied and evidenced, or the specific ones that are not get named. The old -YELLOW rung existed because a 24-31 total had to mean something; without the total -there is nothing for it to mean, and "proceed with known gaps" was the rung most -often used to proceed without reading them. - -Track revision history in audit.md: -```markdown -## Revision History -| Version | Score | Gap-Checked | Gaps | Action | -|---------|-------|-------------|------|--------| -| v1 | 24/40 | NO | 7 | Auto-revised sections 4, 5, 7 | -| v2 | 35/40 | YES | 0 | Accepted | -``` - -Update status.json (include score, rating, gap_checked boolean, gap_count), manifest.md. - -HUMAN REVIEW GATE (conditionally waivable): -After the automated audit completes, prompt for human review before Build: - -"Automated audit complete (score: {X}/40, gap-checked: {YES/NO}). - Before starting Build, this plan should be reviewed by at least one person. - [1] Enter reviewer name(s) to proceed - [2] Waive review (solo mode) — requires documented reason, and only offered - when the waiver condition below holds - [3] View audit summary first" - - -waiver_allowed = (infra_gaps == 0) - AND (score >= 35) - AND (canary_found == true) - - -This is the one place the score is load-bearing, and the asymmetry is the design: -the score cannot let a plan PASS the gate, but a borderline one can remove the -owner's ability to SKIP review. A gameable signal is safe in the direction that -adds friction. The 32-34 band — the scores that sat just above the old threshold — -is exactly where threshold-aiming lands, so a plan scoring there gets a human -whether or not the automated gate passed. - -If the waiver condition fails, option [2] is not offered at all. Do not present it -greyed out with the reason; a visible near-miss invites one more revision aimed at -the waiver rather than at the plan. - -If [1]: Record reviewer name(s) and date in status.json: - { "review": { "reviewers": [{"name": "...", "date": "..."}], "outcome": "accepted" } } - Proceed to Phase 6. - -If [2]: Record waiver in status.json AND stamp it visibly: - { "review": { "waived": true, "reason": "...", "waived_by": "...", - "waiver_condition": { "infra_gaps": 0, "score": X, "canary_found": true } } } - Also append one line to audit.md and to the Phase 9 handoff: - "Review waived (solo mode) by {name} on {date}: {reason}" - A waiver recorded only in machine state is invisible to the person reading the - plan later, which is the person it exists to warn. Proceed to Phase 6. - -If [3]: Show audit-derived review checklist: - - Audit scorecard (8 dimensions with scores) - - Top 3 gaps identified - - Top 5 risks identified - - Key assumptions and their verification status - - Cross-cutting concerns flagged as partially addressed - Then re-prompt [1] or [2]. - -If [1] with reviewer names: Record review in status.json: - { "review": { - "reviewers": [{"name": "...", "date": "...", "decision": "accepted"}], - "outcome": "accepted", - "checklist_presented": true, - "comments": 0 - }} - -For team/leadership plans: review is REQUIRED (option [2] not offered unless -the plan was started in solo mode or the user explicitly requests solo mode). - -For solo mode: review is recommended but waivable with documented reason. - -## Phase 6: BUILD -Question: What got built/changed? - -HARD GATE: ASSUMPTION VERIFICATION (LINT-08) -Before ANY build work begins, check assumptions in status.json: - -``` -For each assumption where impact = HIGH: - If status = unverified: - -> BLOCK entry to Phase 6 - -> Present: "Cannot start Build. These HIGH-impact assumptions are unverified:" - -> List each with its verification method - -> Offer: [1] Verify now [2] Accept risk (waiver) [3] Back to research - - If status = verified: -> PASS - If status = waived: -> PASS (with documented risk acceptance) - If status = falsified: -> BLOCK and return to Phase 3 (approach is invalid) - -For each assumption where impact = MEDIUM and status = unverified: - -> WARN but allow proceeding - -For each assumption where impact = LOW and status = unverified: - -> INFO only -``` - -If user chooses [2] Accept risk (waiver), require: -- Documented risk statement -- Approver name -- Contingency plan if assumption fails -- Update assumption status to "waived" in status.json - -This gate is NOT advisory. It is a hard block. The plan CANNOT proceed to -Build with unverified HIGH-impact assumptions unless explicitly waived. - -This phase actively assists with implementation. - -PARALLEL EXECUTION RULE: -Before starting tickets, analyze the dependency graph from the plan: -- Tickets with NO dependencies on other tickets can run IN PARALLEL as subagents -- Tickets that depend on other tickets must wait until dependencies complete -- Group independent tickets into parallel batches - -``` -Example dependency graph: - POS-5160 (no deps) -> Batch 1 (parallel) - POS-5161 (no deps) -> Batch 1 (parallel) - POS-5162 (no deps) -> Batch 1 (parallel) - POS-5163 (needs 5160) -> Batch 2 (after 5160 completes) - POS-5164 (needs 5162) -> Batch 2 (after 5162 completes) - POS-5165 (needs 5163, 5164) -> Batch 3 (after Batch 2) -``` - -Present the batch plan to the user: -"I can run {N} tickets in parallel (Batch 1: {tickets}). -Batch 2 ({tickets}) depends on Batch 1. Execute Batch 1 in parallel? [Y/n]" - -For each parallel batch, deploy subagents: -- Each subagent gets: ticket description, relevant plan sections, codebase context -- Each subagent writes to a separate branch or file set -- Orchestrator tracks progress and resolves conflicts between parallel work - -DOCUMENT ACTIONS (no approval needed): -- Track ticket progress (update status.json with per-ticket notes) -- Answer questions about the plan ("what file for POS-5162?") -- Provide code context from research -- Suggest next ticket to work on based on dependencies - -CODEBASE ACTIONS (approval required per action): -- "Generate code scaffold for CcReceiptStrings.cs? [Y/n]" -- "Run characterization tests on Printing.FormatReceipt? [Y/n]" -- "Create branch description for Phase 1 tickets? [Y/n]" - -CHANGE CONTROL (backward flow rules with immutable records): -After Phase 3 scope lock, accepted plan documents are immutable. Changes -require a formal Change Record, not silent edits. - -- Minor discovery during build: - 1. Create docs/plans/{date}-{name}/changes/CR-{N}.md with: - - What changed and why - - Which document/section it supersedes - - The NEW content (the CR is the authoritative version going forward) - - Impact on other phases - 2. Add a status line to the TOP of the original document: "SUPERSEDED by CR-{N} on {date}" - Do NOT modify the original document's content. The CR contains the new version. - 3. Update manifest.md with link to the Change Record - 4. Update status.json: { "change_records": [{ "id": "CR-001", "date": "...", "summary": "..." }] } - -- Scope change discovered -> "This changes the scope. Go back to Pre-Plan? [Y/n]" - If yes: create CR-{N} documenting the scope change reason, mark pre_plan - and plan as STALE, return to Phase 3. Original approach.md preserved. - -- New blocker found -> mark current build ticket as BLOCKED with reason, - create CR-{N} documenting the blocker and its impact. - -- Implementation diverges from plan -> create CR-{N} documenting the divergence - and rationale. This replaces informal ADR/change notes. - -Change Record template: -```markdown -# CR-{N}: {Title} -Date: {date} -Author: {name} -Supersedes: {document or section} - -## What Changed -## Why It Changed -## Impact on Other Phases -``` - -Update status.json with build progress, manifest.md. - -No gate. User stays in Build until ready for Impact Review. - -## Phase 7: IMPACT REVIEW -Question: What else does this change affect across layers? - -This is a cross-cutting verification gate. Code that works locally and passes -targeted tests can still break integration edges, scale behavior, transition-state -UX, and downstream consumers. This phase explicitly asks "what did we miss?" - -WHAT IT CHECKS: - -1. INTEGRATION EDGES - - What other modules call the code we changed? - - Did we update all callers, or just the ones we knew about? - - Are there event handlers, webhooks, or async consumers that depend on - the old behavior? - ```bash - # Find all callers of changed functions - grep -rn "{function-name}" --include="*.cs" --include="*.vb" --include="*.ts" \ - . 2>/dev/null | grep -v node_modules | grep -v test - ``` - -2. CROSS-LAYER EFFECTS - - Database: did schema changes affect other queries or stored procedures? - - API: did response format changes break downstream consumers? - - UI: did state changes affect other screens or components? - - Config: did new settings need to be added to all environments? - -3. SCALE AND PERFORMANCE - - Will this change behave differently at production load? - - Did we add queries inside loops? New N+1 patterns? - - Did we add memory-intensive operations without limits? - -4. TRANSITION-STATE BEHAVIOR - - During rollout, old and new code may run simultaneously. - - Feature flags: is the off-state still safe? - - Database migrations: is the schema compatible with both old and new code? - - What happens to in-flight requests during deployment? - -5. TEST DELTA - - What tests existed before vs after? - - Did we add tests for the new behavior? - - Did existing tests need updating and did we miss any? - - Are there integration tests that cover the cross-cutting paths? - -6. STRING PATH REFERENCES (critical for file moves/renames) - If ANY files were moved or renamed during the build phase, scan for stale - string-based path references that don't auto-update. This is a KNOWN gap: - TypeScript/VSCode updates import statements on file move, but does NOT - update string literals. - - Patterns to scan for old file paths: - - vi.mock("old/path") and jest.mock("old/path") - - require("old/path") string arguments - - eslint.config.js ignore arrays - - tsconfig.json paths and includes - - vite.config.ts resolve.alias - - webpack.config.js alias/resolve - - storybook stories globs - - jest.config moduleNameMapper - - package.json scripts that reference file paths - - .env files with path values - - CLAUDE.md or README references to file locations - - ```bash - # For each moved/renamed file, find stale string references - OLD_PATH="{old-file-path-without-extension}" - grep -rn "$OLD_PATH" --include="*.ts" --include="*.tsx" --include="*.js" \ - --include="*.json" --include="*.config.*" --include="*.md" \ - . 2>/dev/null | grep -v node_modules | grep -v ".git/" - ``` - - Any match is a potential stale reference that needs updating. - TypeScript Issue #62835 (open): This is a known gap in all major IDEs. - -7. BACKWARD TRACEABILITY (does every change serve a goal?) - For every file changed during Build, verify the reverse coverage chain: - - Changed file -> Ticket that authorized the change -> Goal it serves - - Orphan detection: - - Files changed with no ticket mapping = SCOPE CREEP (flag) - - Tickets with no changed files = DELIVERY GAP (flag unless explicitly deferred) - - ```bash - # For each changed file, check if it maps to a plan ticket - # Compare git diff file list against ticket-file mapping in status.json - git diff --name-only HEAD~{N}..HEAD | while read FILE; do - grep -q "$FILE" docs/plans/{date}-{name}/status.json || echo "ORPHAN: $FILE" - done - ``` - - Any orphan file must be either: - - Linked to an existing ticket (developer forgot to log it) - - Justified as necessary infrastructure (added to a new ticket) - - Flagged as scope creep for review - - This traceability check is what LINT-11 and LINT-12 are evaluated against; - the registry holds their text and marks both as Phase 7, Full mode only. - -PROCESS: -PARALLELIZATION RULE: The 5 check dimensions are independent. Deploy parallel -subagents for each dimension to speed up the review. - -Deploy up to 3 subagents in parallel (scale to the size of the change): - -SUBAGENT A - Integration & Cross-Layer (Sonnet): -Objective: Find all callers of changed code, check integration edges and cross-layer effects -Tools: Read, Grep, Glob, Bash -Checks: dimensions 1 (Integration Edges) and 2 (Cross-Layer Effects) - -SUBAGENT B - Scale & Transition State (Sonnet): -Objective: Analyze performance impact and transition-state safety -Tools: Read, Grep, Glob -Checks: dimensions 3 (Scale) and 4 (Transition-State) - -SUBAGENT C - Test Delta, String Paths & Backward Trace (Sonnet): -Objective: Compare test coverage before vs after, scan for stale string path references, AND verify backward traceability of all changed files -Tools: Read, Grep, Glob, Bash -Checks: dimensions 5 (Test Delta), 6 (String Path References), and 7 (Backward Traceability) - -Each subagent writes its section to a temp file. Orchestrator synthesizes. - -Steps: -1. Read the build phase's changed files from status.json -2. Deploy subagents with the list of changed files + relevant audit data -3. Each subagent scans for its dimensions -4. Cross-reference with docs/audit/dependency-map.md (if exists) -5. Cross-reference with docs/audit/integration-scan.md (if exists) -6. Synthesize all subagent findings -7. Flag any untested integration path -8. Present findings as a checklist - -OUTPUT: Written to docs/plans/{date}-{plan-name}/impact-review.md with: - -```markdown -# Impact Review: {Plan Name} -Date: {date} -Changed files: {count} -Integration edges checked: {count} - -## Cross-Cutting Findings - -| # | Finding | Severity | File | Checked? | -|---|---------|----------|------|----------| -| 1 | OrderReceipt.tsx also formats receipt strings | HIGH | src/features/orders/ | [VERIFY] | -| 2 | CCApproval.vb has hardcoded receipt text | MEDIUM | POSetcPOS/CreditCard/ | [VERIFY] | -| 3 | Print preview doesn't use new string table | LOW | POSetcPOS/Printer/ | [VERIFY] | - -## Integration Paths Not Covered by Tests -- [list of caller->callee paths that have no test coverage] - -## Scale Concerns -- [any performance-related observations] - -## Transition-State Risks -- [anything that could break during partial rollout] - -## Checklist Before Test Phase -- [ ] All callers of changed functions verified -- [ ] No untested integration paths remaining (or explicitly accepted) -- [ ] Scale behavior reviewed for production load -- [ ] Feature flag off-state tested -- [ ] Database migration compatible with old and new code -- [ ] No orphan code changes (all changes traced to tickets) [LINT-11] -- [ ] No orphan tickets (all tickets have implementation or are deferred) [LINT-12] - -TESTING METHODOLOGY VERIFICATION: -For each deliverable with an assigned testing methodology (from Phase 4): -- [ ] Methodology is appropriate for the type of change (not defaulting to "unit tests") -- [ ] Test authorship is separate from implementation authorship for AI-generated code -- [ ] Database changes use Expand/Contract with forward AND backward migration scripts -- [ ] API changes have contract tests covering old code + new schema AND new code + old schema -- [ ] Characterization tests captured BEFORE refactoring (not after) -- [ ] AI Failure Mode Checklist applied to all AI-generated deliverables - -Database Migration Testing (if applicable): - -| Phase | What to Test | Method | -|-------|-------------|--------| -| Expand | New columns/tables exist, old untouched | Structural assertions | -| Migrate | Row counts, checksums, referential integrity preserved | Characterization + Shadow | -| Contract | Old structures removed, no orphan refs, all code uses new schema | Structural assertions | -| Rollback | Backward migration restores original state | Apply -> verify -> rollback -> verify | -| Backward compat | Old code + new schema works, new code + old schema works | Contract Testing | -| Performance | Queries under threshold, indexes present, no N+1 | Property-Based + Profiling | -``` - -GATE: User confirmation required. -"Impact review complete. {N} cross-cutting findings, {M} untested integration -paths. Review the findings and confirm before proceeding to Test." - -If HIGH severity findings exist: -"HIGH severity: {finding}. This should be addressed before Test phase. -Fix it now, or accept the risk and proceed? [fix / accept with reason]" - -Update status.json, manifest.md. - -## Phase 8: TEST -Question: Does it work safely? - -DOCUMENT ACTIONS (automatic): -Write docs/plans/{date}-{plan-name}/test-plan.md with: -- Per-phase test matrix (test name, type, what it verifies) -- Edge cases prompted by plan context -- Characterization test candidates for changed code -- Each criterion categorized as AUTOMATED or MANUAL (see below) - -METHODOLOGY-SPECIFIC TEST PROCEDURES: -Based on the testing methodology assigned in Phase 4, execute the appropriate -test procedure for each deliverable. Reference the full framework at -docs/planning-techniques/10-testing-methodology-selection.md. - -IF methodology = expand_contract: -Execute all 18 steps of the database migration test checklist: - - EXPAND PHASE: - - [ ] Forward migration script runs cleanly on empty DB - - [ ] Forward migration script runs cleanly on production-like data - - [ ] New columns/tables exist with correct types and constraints - - [ ] Old columns/tables are untouched (no dropped columns, no renamed columns) - - [ ] Old code works against expanded schema (backward compatible) - - [ ] New code works against expanded schema - - MIGRATE PHASE: - - [ ] Dual-write triggers or application-level dual-write is active - - [ ] Backfill of existing data completes without errors - - [ ] Row counts match pre/post migration - - [ ] Checksums match pre/post migration (normalize volatile data) - - [ ] Referential integrity intact (no orphan foreign keys) - - [ ] Shadow comparison of old vs new query results matches - - CONTRACT PHASE: - - [ ] Backward (rollback) migration script restores original state - - [ ] New code works against contracted schema - - [ ] Old structures removed cleanly (no leftover columns/tables) - - [ ] No orphan references to removed columns/tables in codebase - - [ ] Indexes exist on new columns (no missing index regressions) - - [ ] Query performance within acceptable bounds on new schema - -IF methodology = tdd: - - [ ] Test suite generated from spec BEFORE implementation - - [ ] All tests fail initially (Red phase verified) - - [ ] Implementation passes all tests (Green phase) - - [ ] Refactoring does not break tests - -IF methodology = characterization: - - [ ] Golden master baseline captured BEFORE changes - - [ ] Post-change output matches baseline (or divergences explicitly approved) - - [ ] Volatile data normalized before comparison (timestamps, auto-increment IDs) - -IF methodology = contract_testing: - - [ ] Consumer contracts defined - - [ ] Provider verification passes - - [ ] Old code + new schema validated against contracts - - [ ] New code + old schema validated against contracts - -IF methodology = shadow_parallel: - - [ ] Dual-write infrastructure in place - - [ ] Comparison monitoring active - - [ ] Divergence rate below threshold before cutover - -IF methodology = property_based: - - [ ] Invariants defined and documented - - [ ] Input generators cover edge cases - - [ ] All properties hold under generated inputs - -IF methodology = bdd: - - [ ] Gherkin specs written by humans (product/QA) - - [ ] Step definitions wired and passing - - [ ] All Given/When/Then scenarios covered - -IF methodology = snapshot_approval: - - [ ] Snapshots captured and approved by humans - - [ ] No blind snapshot updates (each change reviewed) - -IF methodology = mutation_testing: - - [ ] Mutation testing tool configured and run - - [ ] Mutation score above team-calibrated threshold - - [ ] All surviving mutants reviewed and justified - -CODEBASE ACTIONS (approval required): -- "Generate characterization tests for {function}? [Y/n]" -- "Create test stubs for new code? [Y/n]" - -TWO-TIER VERIFICATION: -Split all success criteria into two categories. Run automated first, -then pause for manual verification. - -TIER 1 — AUTOMATED VERIFICATION (run without human intervention): -- [ ] All critical path tests pass (run test command) -- [ ] TypeScript/code compiles with no errors (run build command) -- [ ] No lint errors in changed files -- [ ] Characterization baseline captured for any refactored code -- [ ] Audit score is GREEN with gap-checked = YES, or YELLOW with gap-checked = YES - -Run all Tier 1 checks. Report results. Then PAUSE: - -``` -Phase 8 — Automated Verification Complete - -Automated checks passed: -- [list each Tier 1 check and its result] - -Ready for manual verification. Please perform these checks: -- [ ] [Manual item 1] -- [ ] [Manual item 2] - -Let me know when manual testing is complete so I can proceed to Handoff. -``` - -TIER 2 — MANUAL VERIFICATION (requires human testing): -- [ ] No open P0/P1 defects against this plan -- [ ] Rollback plan has been validated (tested in staging or reviewed by ops) -- [ ] Key user flows work as expected in staging/preview -- [ ] Edge cases identified in test-plan.md have been manually verified -- [ ] Deployment runbook reviewed by someone other than the author - -Do NOT auto-check Tier 2 items. Wait for human confirmation on each. -Track which items the human confirmed and when: - { "test_gate": { "automated": { "passed": 5, "failed": 0 }, "manual": { "verified": 4, "pending": 1, "verified_by": "J. Smith", "date": "..." } } } - -HARD READINESS GATE: -Before proceeding to Handoff, ALL of these must be true: -- All Tier 1 (automated) checks pass -- All Tier 2 (manual) checks confirmed by a human -- No Tier 2 items left in "pending" state - -If gate fails, report what's missing and stay in Test phase. - -Update status.json, manifest.md. - -## Phase 9: HANDOFF -Question: What happens next? - -READINESS CHECK before entering this phase: -- Test phase complete (or explicitly waived) -- Audit score GREEN or YELLOW with gap-checked = YES -- No BLOCKED tickets remaining (or explicitly deferred) -- Rollback plan documented - -Context-aware guidance based on situation: -- If ready to ship: specific deployment sequence with verification steps -- If gaps remain: prioritized list of what to fix with reasoning -- If timeline pressure: critical path items vs deferrable items - -Update manifest.md with final status, decisions made, lessons learned. -Update status.json: handoff -> complete. - -Present final summary: -``` -Plan: {name} - Complete - -Phases: 9/9 -Duration: {started} to {completed} -Audit score: {score}/40 ({rating}) -Tickets: {done}/{total} - -Key decisions: [from approach.md and change records] -Change records: {count} (see changes/ folder) -What shipped: [summary] -What's deferred: [if anything] -``` - - - -Path-scoped fingerprinting (not full repo SHA): - -Each phase records hashes of ONLY the files it referenced. -Three freshness levels: -- FRESH: referenced files unchanged since phase completed -- WARNING: related files in same directory changed (may affect findings) -- STALE: directly referenced files changed (findings likely invalid) - -Invalidation cascade: -- brainstorm.md goals change -> approach.md becomes STALE -- approach.md scope changes -> confidence.md becomes STALE (tools/patterns may have changed) -- approach.md scope changes -> docs/specs/{plan-name}.md becomes STALE -- docs/specs/{plan-name}.md changes after audit -> audit.md becomes STALE -- audit.md revision adds new tools/patterns -> confidence.md becomes WARNING (needs reinforcement) -- source docs change after research -> research becomes WARNING - -On resume, check freshness of all completed phases and report any staleness. - - - -| Failure | Recovery | -|---------|----------| -| Source folder unreadable | Skip doc cleanup, continue with codebase + web | -| Codebase scan finds nothing | Note "no existing code found", proceed | -| MCP/web research unavailable | Skip Track 3 or use codebase-only research, tag "[EXTERNAL RESEARCH UNAVAILABLE]" | -| Phase partially complete | Save to status.json, allow resume | -| Existing plan folder | Ask: resume existing or create {name}-2? | -| status.json corrupted | Rebuild from existing files in plan folder | -| Referenced files deleted | Mark findings as STALE, suggest re-research | - - - -Only suggest these commands (all verified to exist as command files): -/deepgrade:plan, /deepgrade:plan-status, /deepgrade:quick-audit, -/deepgrade:quick-plan, /deepgrade:quick-cleanup, /deepgrade:documentation, -/deepgrade-audit:codebase-characterize, /deepgrade-readiness:readiness-scan, -/deepgrade-audit:codebase-audit, /deepgrade-audit:codebase-delta, -/deepgrade-audit:codebase-security, /deepgrade-audit:codebase-gates, -/deepgrade-readiness:readiness-generate, /deepgrade:help - diff --git a/plugins/deepgrade/skills/plan/SKILL.md b/plugins/deepgrade/skills/plan/SKILL.md new file mode 100644 index 0000000..a88332f --- /dev/null +++ b/plugins/deepgrade/skills/plan/SKILL.md @@ -0,0 +1,319 @@ +--- +name: plan +description: (deepgrade) Start or resume a guided plan. Walks you through 9 phases from idea to handoff, with AI assistance at every step. Produces documents by default; codebase writes require your approval. Pass a plan name to start new or resume existing. Optionally pass source material with 'from'. Use when the user asks to plan a feature, start or resume a plan, or take an idea through brainstorm, research, audit, build, and handoff. +argument-hint: "[plan-name] [from docs/path or 'idea: description']" +allowed-tools: Read, Write, Grep, Glob, Bash, Task +--- + + +You are a planning and implementation assistant. You guide engineers through +a structured 9-phase workflow that takes ANY starting input (vague idea, docs +folder, Jira ticket, existing spec) and produces a complete, audited, +executable plan with implementation support. + +You are BOTH a planning tool AND an implementation helper. You produce +documents automatically. You assist with code changes only on explicit approval. + + + +USE PARALLEL AGENTS WHENEVER POSSIBLE. + +Anthropic's research shows multi-agent with parallel subagents outperforms +single-agent by 90%+ and reduces time by up to 90% for complex tasks. + +RULE: If a phase has 2+ tasks that don't depend on each other, +run them as parallel subagents. Do NOT run them sequentially. + +When to parallelize (by phase): +- Phase 2 (Research): 3 tracks are independent -> 3 parallel subagents +- Phase 5 (Audit): 5 specialists are independent -> 5 parallel subagents (already done) +- Phase 6 (Build): Independent tickets -> batch into parallel groups +- Phase 7 (Impact): 5 check dimensions -> 3 parallel subagents + +When NOT to parallelize: +- Phase 1 (Brainstorm): Interactive with user, must be sequential +- Phase 3 (Pre-Plan): Depends on research, must be sequential +- Phase 4 (Plan): Depends on scope lock, must be sequential +- Phase 8 (Test): Tests may have execution order dependencies +- Phase 9 (Handoff): Single synthesis step + +Subagent delegation rules (from Anthropic's 8 principles): +1. Give each subagent a SPECIFIC, scoped objective (not vague instructions) +2. Define what THIS subagent covers vs what OTHER subagents cover +3. Specify the output format and file path +4. Specify which tools the subagent should use +5. Set boundaries: what files/directories to focus on +6. Use Sonnet for workers, keep orchestration in the current agent +7. Store subagent outputs to filesystem (prevents context loss) +8. After all subagents complete, synthesize and cross-reference findings + +Scaling rules: +- 1-2 independent tasks: just run them (overhead of subagents isn't worth it) +- 3+ independent tasks: parallel subagents +- 5+ independent tasks: batch into 3-5 subagent groups + + + +9 phases, each answering exactly ONE question: + +| # | Phase | Question | Gate | +|---|-------|----------|------| +| 1 | Brainstorm | What problem are we solving? | User confirmation | +| 2 | Research | What is true about our situation? | Auto (tool decides "enough") | +| 3 | Pre-Plan | What should be in scope? | User confirmation (scope lock) | +| 4 | Plan | How will we execute? | User confirmation | +| 5 | Audit | What is weak or missing? | Evaluator-optimizer loop + human review | +| 6 | Build | Execute + track progress | Per-action approval for code | +| 7 | Impact Review | What else does this change affect? | User confirmation | +| 8 | Test | Does it work safely? | Hard pass/fail gate | +| 9 | Handoff | What happens next? | Readiness check | + + + +Four tiers of approval: +1. READ-ONLY (no approval): grep, read files, search web +2. DOCUMENT WRITE (no approval): write to docs/plans/{date}-{name}/ +3. CODEBASE WRITE (approval required): test files, code scaffolds, generated code +4. SIDE-EFFECT COMMANDS (approval required): git operations, package installs, builds + + + +The plan folder is a HOMEBASE that contains plan-specific files and a manifest +linking to all related documents. Actual project documents (specs, ADRs, PRDs, +audits) live in standard project docs/ locations where developers expect them. + +PLAN FOLDER (homebase): docs/plans/YYYY-MM-DD-{plan-name}/ + manifest.md <- Human-readable index linking to ALL related files + status.json <- Machine-readable progress, staleness, resume state + brainstorm.md <- Phase 1 (plan-specific, lives here) + approach.md <- Phase 3 (plan-specific, lives here) + confidence.md <- Phase 3 (created), Phase 5 (reinforced) + audit.md <- Phase 5 (plan-specific, lives here) + impact-review.md <- Phase 7 (plan-specific, lives here) + test-plan.md <- Phase 8 (plan-specific, lives here) + research/ <- Phase 2 (plan-specific, lives here) + findings.md + reference-data.json + intake/ <- Cleaned source docs + changes/ <- Immutable change records (CR-001, CR-002, ...) + troubleshooting/ <- /deepgrade:troubleshoot logs linked to this plan + +PROJECT DOCUMENTS (standard locations, linked from manifest): + docs/specs/{plan-name}.md <- Phase 4 spec + docs/adr/ADR-{topic}.md <- ADRs created during plan + docs/prd/{feature}.md <- PRDs created during plan + +CODEBASE (on approval only): + Test files in project test directories <- Phase 7 golden master tests + Code scaffolds in source directories <- Phase 6 generated code + +The manifest.md links everything together with creation dates: +```markdown +# Plan: {Name} +Created: {date} +Status: Phase {N} - {name} +Owner: {name} + +## Plan Files (this folder) +- [Brainstorm](brainstorm.md) - {date} +- [Approach](approach.md) - {date} +- [Confidence Brief](confidence.md) - {date} (reinforced: {date}) +- [Research](research/findings.md) - {date} +- [Audit](audit.md) - {date} +- [Impact Review](impact-review.md) - {date} +- [Test Plan](test-plan.md) - {date} + +## Project Documents (in docs/) +- [Spec: {name}](../../docs/specs/{plan-name}.md) - {date} +- [ADR: {topic}](../../docs/adr/ADR-{topic}.md) - {date} + +## Change Records +| CR | Date | Summary | +|----|------|---------| +| (none yet) | | | + +## Codebase Files +- {path to test files} - {date} +- {path to generated code} - {date} +``` + + + +## Step 0: Detect Intent and Create/Resume Workspace + +Parse $ARGUMENTS: +- If a plan folder matching the name exists in docs/plans/ -> RESUME (read status.json) +- If "from" keyword present -> NEW plan with source material +- If just a name -> NEW plan from scratch + +For NEW plans: +```bash +TODAY=$(date +%Y-%m-%d) +PLAN_NAME="{name}" +PLAN_DIR="docs/plans/${TODAY}-${PLAN_NAME}" +mkdir -p "$PLAN_DIR/research/intake" + +# Also ensure standard doc directories exist +mkdir -p docs/specs docs/adr docs/prd docs/audit docs/test-plans +``` + +Suggest a default name based on input. Ask the user to confirm or rename: +``` +Suggested plan name: worldpay-canada +This will create: docs/plans/2026-03-07-worldpay-canada/ + [1] Use this name + [2] Enter a different name +``` + +Create initial status.json: +```json +{ + "schema_version": 1, + "plan_name": "{name}", + "plan_dir": "docs/plans/{date}-{name}", + "created": "{ISO date}", + "current_phase": "brainstorm", + "documents": {}, + "phases": { + "brainstorm": {"status": "not_started"}, + "research": {"status": "not_started"}, + "pre_plan": {"status": "not_started"}, + "plan": {"status": "not_started"}, + "audit": {"status": "not_started"}, + "build": {"status": "not_started"}, + "impact_review": {"status": "not_started"}, + "test": {"status": "not_started"}, + "handoff": {"status": "not_started"} + } +} +``` + +Create initial manifest.md: +```markdown +# Plan: {Name} +Created: {date} +Status: Phase 1 - Brainstorm +Owner: TBD + +## Plan Files (this folder) +| File | Phase | Created | +|------|-------|---------| +| [Brainstorm](brainstorm.md) | 1 | Pending | +| [Research](research/findings.md) | 2 | Pending | +| [Approach](approach.md) | 3 | Pending | +| [Confidence](confidence.md) | 3+5 | Pending | +| [Audit](audit.md) | 5 | Pending | +| [Impact Review](impact-review.md) | 7 | Pending | +| [Test Plan](test-plan.md) | 8 | Pending | + +## Project Documents (in docs/) +| Document | Type | Path | Created | +|----------|------|------|---------| +| (none yet) | | | | + +## Codebase Files +| File | Type | Created | +|------|------|---------| +| (none yet) | | | + +## Progress +| Phase | Status | +|-------|--------| +| 1. Brainstorm | In Progress | +| 2. Research | Not Started | +| 3. Pre-Plan | Not Started | +| 4. Plan | Not Started | +| 5. Audit | Not Started | +| 6. Build | Not Started | +| 7. Impact Review | Not Started | +| 8. Test | Not Started | +| 9. Handoff | Not Started | +``` + +UPDATE MANIFEST AT EVERY PHASE: When any phase creates or links a document, +update both manifest.md (add row to the appropriate table with date) and +status.json (add file path to the documents object). + +For RESUME: +Read status.json. Find the current phase. Show progress and offer to continue: +``` +Plan: {name} +Current phase: {phase} ({status}) +Last updated: {date} + +[show progress table from manifest.md] + +Continue from {phase}? +``` + + +## Phases 1-9: load the phase file on entry + +The nine phases live in one file each under `${CLAUDE_SKILL_DIR}/phases/`. Skill +content enters the conversation once and is not re-read after auto-compaction, so +a single 1,700-line file silently loses its later phases in exactly the long +sessions this workflow produces. The split is the fix: each phase is read when it +is entered, so its instructions are always the most recent thing in context. + +RULE: On entering a phase (new plan, gate passed, or RESUME landing in it), READ +the phase file with the Read tool BEFORE doing any work in that phase. Re-read it +after any compaction. Read only the current phase; do not read ahead. + +| # | Phase | File | +|---|-------|------| +| 1 | Brainstorm | `${CLAUDE_SKILL_DIR}/phases/phase-1-brainstorm.md` | +| 2 | Research | `${CLAUDE_SKILL_DIR}/phases/phase-2-research.md` | +| 3 | Pre-Plan | `${CLAUDE_SKILL_DIR}/phases/phase-3-pre-plan.md` | +| 4 | Plan | `${CLAUDE_SKILL_DIR}/phases/phase-4-plan.md` | +| 5 | Audit | `${CLAUDE_SKILL_DIR}/phases/phase-5-audit.md` | +| 6 | Build | `${CLAUDE_SKILL_DIR}/phases/phase-6-build.md` | +| 7 | Impact Review | `${CLAUDE_SKILL_DIR}/phases/phase-7-impact-review.md` | +| 8 | Test | `${CLAUDE_SKILL_DIR}/phases/phase-8-test.md` | +| 9 | Handoff | `${CLAUDE_SKILL_DIR}/phases/phase-9-handoff.md` | + +Paths use forward slashes on every platform. If a phase file cannot be read, stop +and report the path; do not improvise the phase from memory. + + + + +Path-scoped fingerprinting (not full repo SHA): + +Each phase records hashes of ONLY the files it referenced. +Three freshness levels: +- FRESH: referenced files unchanged since phase completed +- WARNING: related files in same directory changed (may affect findings) +- STALE: directly referenced files changed (findings likely invalid) + +Invalidation cascade: +- brainstorm.md goals change -> approach.md becomes STALE +- approach.md scope changes -> confidence.md becomes STALE (tools/patterns may have changed) +- approach.md scope changes -> docs/specs/{plan-name}.md becomes STALE +- docs/specs/{plan-name}.md changes after audit -> audit.md becomes STALE +- audit.md revision adds new tools/patterns -> confidence.md becomes WARNING (needs reinforcement) +- source docs change after research -> research becomes WARNING + +On resume, check freshness of all completed phases and report any staleness. + + + +| Failure | Recovery | +|---------|----------| +| Source folder unreadable | Skip doc cleanup, continue with codebase + web | +| Codebase scan finds nothing | Note "no existing code found", proceed | +| MCP/web research unavailable | Skip Track 3 or use codebase-only research, tag "[EXTERNAL RESEARCH UNAVAILABLE]" | +| Phase partially complete | Save to status.json, allow resume | +| Existing plan folder | Ask: resume existing or create {name}-2? | +| status.json corrupted | Rebuild from existing files in plan folder | +| Referenced files deleted | Mark findings as STALE, suggest re-research | + + + +Only suggest these commands (all verified to exist as command files): +/deepgrade:plan, /deepgrade:plan-status, /deepgrade:quick-audit, +/deepgrade:quick-plan, /deepgrade:quick-cleanup, /deepgrade:documentation, +/deepgrade-audit:codebase-characterize, /deepgrade-readiness:readiness-scan, +/deepgrade-audit:codebase-audit, /deepgrade-audit:codebase-delta, +/deepgrade-audit:codebase-security, /deepgrade-audit:codebase-gates, +/deepgrade-readiness:readiness-generate, /deepgrade:help + diff --git a/plugins/deepgrade/skills/plan/phases/phase-1-brainstorm.md b/plugins/deepgrade/skills/plan/phases/phase-1-brainstorm.md new file mode 100644 index 0000000..6e2ef9d --- /dev/null +++ b/plugins/deepgrade/skills/plan/phases/phase-1-brainstorm.md @@ -0,0 +1,28 @@ +# Phase 1: BRAINSTORM + +Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. + +Question: What problem are we solving? + +IF input is a vague idea or just a plan name: + Ask structured questions ONE AT A TIME: + 1. "What problem are you trying to solve?" + 2. "Who is affected by this problem?" + 3. "Why is this happening now? What triggered it?" + 4. "What does success look like?" + +IF input includes source docs (from keyword): + Read the source material, draft a problem statement, ask: + "Based on what I read, here's the problem as I understand it: [statement]. + Is this right, or should I adjust?" + +IF input includes an existing ticket or spec: + Extract the problem statement, confirm with user. + +Write brainstorm.md with: Problem Statement, Goals, Non-Goals, Open Questions, Ownership (plan owner, tech reviewer, business approver - ask or default TBD). + +Update status.json: brainstorm -> complete, research -> not_started +Update manifest.md progress table. + +GATE: Ask user "Problem defined. Ready to move to research? [Y/n]" +On confirm -> proceed to Phase 2. diff --git a/plugins/deepgrade/skills/plan/phases/phase-2-research.md b/plugins/deepgrade/skills/plan/phases/phase-2-research.md new file mode 100644 index 0000000..742a0e4 --- /dev/null +++ b/plugins/deepgrade/skills/plan/phases/phase-2-research.md @@ -0,0 +1,83 @@ +# Phase 2: RESEARCH + +Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. + +Question: What is true about our situation? + +Run three research tracks IN PARALLEL using subagents: + +PARALLELIZATION RULE: The three tracks are independent. Deploy them +simultaneously as subagents, each with its own context window. Do NOT +run them sequentially. Each writes its output to the plan folder. + +TRACK 1 - CODEBASE SCAN (Subagent: Sonnet): +Objective: Find all related code in the current codebase. +Tools: Read, Grep, Glob, Bash +Output: docs/plans/{date}-{name}/research/codebase-scan.md +```bash +# Search for related code based on brainstorm keywords +grep -ri "{keywords}" --include="*.cs" --include="*.vb" --include="*.ts" \ + --include="*.config" --include="*.json" . 2>/dev/null | grep -v node_modules | head -30 +``` +Read the key files found. Note existing patterns, current implementation, dependencies. + +TRACK 2 - SOURCE DOC CLEANUP (Subagent: Sonnet, if docs were provided): +Objective: Clean and structure provided source documents. +Tools: Read, Write, Bash +Output: docs/plans/{date}-{name}/research/intake/ (structured files) +Read all files in the source folder. Extract structured data per content type. +Write cleaned data to research/intake/. + +TRACK 3 - BEST PRACTICES (Subagent: Sonnet, if external search tools available): +Objective: Find how others solved similar problems. +Tools: Read, WebSearch, WebFetch, plus any connected MCP search tool whose name +ends in `__ref_search_documentation`, `__ref_read_url`, `__web_search_exa`, +`__web_fetch_exa`, or `__perplexity_ask` (see the `deepgrade:mcp-research` skill — +match by suffix, never by bare name) +Output: docs/plans/{date}-{name}/research/best-practices.md + +Search strategy (use in order, stop when sufficient): +1. Ref: Search framework/library docs for the specific technologies in scope. + Use ref_search_documentation with a complete question (not keywords). +2. Exa: Search for code examples of the pattern being considered. + Use web_search_exa for both implementation examples and general patterns, then + web_fetch_exa on the one result worth reading in full. +3. Perplexity: If Ref + Exa are insufficient, ask a targeted research question. + Use perplexity_ask for focused answers with citations. +4. WebSearch/WebFetch: Fallback if MCP tools are not available. + +If NO external search tools are available: + Fall back to codebase-only research using built-in tools. + Tag in findings.md: "[EXTERNAL RESEARCH UNAVAILABLE — findings based on codebase and training data only]" + +SYNTHESIS (after all tracks complete): +Read all three track outputs. Cross-reference findings. +Write docs/plans/{date}-{name}/research/findings.md as the combined summary. + +STOP RUBRIC - Research is DONE when: +- All brainstorm open questions are answered or explicitly deferred +- At least one viable implementation path is identified +- Top risks have mitigation ideas +- Remaining unknowns are non-blocking + +When stop criteria are met, present findings: +``` +Research complete. Key findings: + +CODEBASE: [what exists, what we can reuse] +SOURCE DOCS: [key facts extracted] +BEST PRACTICES: [recommended approach] + +What we still don't know: [gaps, with assessment: blocking vs non-blocking] +Open questions resolved: [X of Y] + +Ready to set scope. +``` + +Write research/findings.md and research/reference-data.json. +Record path-scoped fingerprints for referenced files (not full repo SHA). + +Update status.json: research -> complete with file hashes +Update manifest.md: add research files to Plan Files table with date. + +GATE: Automatic. Tool proceeds when stop rubric is met. diff --git a/plugins/deepgrade/skills/plan/phases/phase-3-pre-plan.md b/plugins/deepgrade/skills/plan/phases/phase-3-pre-plan.md new file mode 100644 index 0000000..a1b3bc2 --- /dev/null +++ b/plugins/deepgrade/skills/plan/phases/phase-3-pre-plan.md @@ -0,0 +1,250 @@ +# Phase 3: PRE-PLAN + +Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. + +## Contents + +- Scope, options analysis, and scope lock +- Confidence brief (required): why, success criteria, timebox +- Confidence brief template +- Cross-plan references +- Entry prioritization and impact classification +- Source credibility and URL verification +- Conflicting evidence +- Confidence falsification (post-scope-lock) +- Anchor ids +- Gate + +Question: What should be in scope? + +Produce an alignment checkpoint in approach.md: + +- Scope: IN list and OUT list +- Options Analysis (REQUIRED): Evaluate minimum 2 approaches before selecting: + + For each option: + - Name and approach description + - Pros and cons + - Risk level (LOW/MEDIUM/HIGH) + - Rollback complexity (LOW/MEDIUM/HIGH) + + Comparison matrix scoring each option against: + - Implementation ease, Timeline, Strategic value, Risk profile, Rollback complexity + + Decision Rationale: WHY the selected option won, referencing specific criteria. + Losing options: document "would revisit if" conditions. + +- Approach/Pattern: which pattern and WHY (strangler fig, feature flag, migration, new build, integration) +- Top 3 Risks: each with impact level and mitigation +- Constraints: timeline, team, technology +- Dependencies: internal, external, hard blockers, soft dependencies + +Present to user for confirmation. This is the SCOPE LOCK. + +CONFIDENCE BRIEF (REQUIRED — written after approach.md, before gate): + +WHY THIS EXISTS: Without external evidence backing, plan decisions rest on +the authoring agent's training data alone — which may be outdated, biased, or +hallucinated. Stakeholders reviewing plans cannot distinguish "this is industry +standard" from "this is what the AI made up." The confidence brief solves this +by requiring verifiable external evidence for every significant tool, method, +and pattern choice. + +SUCCESS CRITERIA: +- Every HIGH-impact entry has at least one verifiable reference link +- A stakeholder unfamiliar with the plan can read confidence.md and understand + why the chosen approach is industry-proven (not just "the AI suggested it") +- No fabricated company examples (see SOURCE CREDIBILITY below) + +TIMEBOX: The confidence brief should take no longer than the approach.md itself. +- MAX ENTRIES: 10 entries per plan (prioritize by impact). If more than 10 + items are identified, defer LOW-impact items with a note: "Deferred: {item} + (LOW impact, not blocking scope lock)" +- If entry count exceeds 10, stop and present the top 10 sorted by impact. + User can request additional entries after scope lock. + +Step breakdown (approximate effort per entry): +1. Discovery — scan approach/research/brainstorm for items (~1 min total) +2. Drafting — write "what it is" and "connection to plan" (~1 min per entry) +3. Evidence gathering — search for "who uses it" and references (~2 min per HIGH, ~1 min per MEDIUM) +4. Cross-plan search — check existing confidence.md files (~30 sec per entry) +5. Review — verify URLs for HIGH-impact entries if web tools available (~1 min per HIGH) + +If the plan is under timeline pressure, skip steps 4-5 for MEDIUM and LOW +entries and mark them with "[CROSS-PLAN CHECK DEFERRED]" and "[URL VERIFICATION +DEFERRED]". HIGH-impact entries MUST always complete steps 3-5 regardless of +timeline pressure — these entries drive scope lock decisions and cannot be deferred. + +After writing approach.md, generate confidence.md — a self-contained knowledge +brief that grounds every tool, method, and pattern choice in external industry +evidence. This file is stakeholder-readable: someone outside the plan should +be able to read it and understand why these choices are solid. + +Scan the approach.md, research/findings.md, and brainstorm.md for: +- New dependencies/packages (NuGet, npm, pip, etc.) +- Methodologies or patterns chosen (strangler fig, expand/contract, CQRS, etc.) +- Best practices referenced (DORA metrics, chaos engineering, etc.) +- Frameworks, libraries, or tools introduced + +For EACH item found, write an entry in confidence.md using this structure: + +```markdown +# Confidence Brief: {Plan Name} +Created: {date} (Phase 3) +Last reinforced: {date} (Phase 5, if applicable) + +> This document explains WHY the tools, methods, and patterns in this plan +> are industry-proven choices. Each entry defines what it is, who uses it +> at scale, and why it works — then briefly connects it to this plan. + +--- + +## Dependencies & Tools + +### {Package/Tool Name} {version} +**What it is:** {1-2 sentence definition — what the tool does, what problem it solves} + +**Who uses it at scale:** +- **{Company 1}** — {how they use it, what scale, what outcome} +- **{Company 2}** — {how they use it, what scale, what outcome} + +**Why it works:** {1 paragraph — the engineering reason this tool is effective, +what architectural property it provides, what failure mode it prevents} + +**Reference:** [{title}]({url}) ← link to official docs, conference talk, or case study + +**Connection to this plan:** {1-2 sentences — why we chose this specifically, +which plan goal it serves} + +**Also referenced in:** [{other-plan-name}](../../{other-plan-dir}/confidence.md#{anchor}) ← only if another plan uses the same tool + +--- + +## Methods & Patterns + +### {Method/Pattern Name} +**What it is:** {1-2 sentence definition} + +**Origin:** {Who created/popularized it — e.g., "Martin Fowler (2004)", +"Netflix engineering team (2011)", "Microsoft Azure Architecture Center"} + +**Who uses it at scale:** +- **{Company 1}** — {context and outcome} +- **{Company 2}** — {context and outcome} + +**Why it works:** {1 paragraph — the engineering principle, what it optimizes +for, what tradeoff it makes explicit} + +**Reference:** [{title}]({url}) + +**Connection to this plan:** {1-2 sentences linking to specific plan phases or decisions} + +**Also referenced in:** [{other-plan-name}](...) ← only if applicable + +--- + +## Best Practices & Standards + +### {Practice Name} +**What it is:** {1-2 sentence definition} + +**Advocated by:** {Organization or thought leader — e.g., "DORA/Google", +"OWASP", "12-Factor App (Heroku)"} + +**Industry evidence:** +- {Specific metric or finding — e.g., "Teams using trunk-based development + deploy 973x more frequently (DORA State of DevOps 2023)"} + +**Why it works:** {1 paragraph} + +**Reference:** [{title}]({url}) + +**Connection to this plan:** {1-2 sentences} +``` + +CROSS-PLAN REFERENCES: +Before writing each entry, search existing plan folders for confidence.md files: +```bash +find docs/plans/ -name "confidence.md" -exec grep -l "{tool-or-pattern-name}" {} \; +``` +If found in another plan, add an "Also referenced in" link. The entry in THIS +file must still be self-contained (full context) — the link is supplemental, +not a replacement for content. A reader should never need to open another +plan's confidence.md to understand this one. + +ENTRY PRIORITIZATION: +- HIGH-impact items (core dependencies, primary pattern): full entry with reference link REQUIRED +- MEDIUM-impact items (supporting tools, secondary patterns): full entry, reference link optional +- LOW-impact items (dev tooling, standard practices): shorter entry, no reference link required + +Impact classification criteria (rationale REQUIRED for each classification): +- HIGH: item is on the critical path, a wrong choice causes plan failure or rework + (e.g., primary database, core framework, architectural pattern) + Rationale example: "HIGH — Markdig is the sole markdown rendering engine; if it + can't handle our edge cases, the entire doc pipeline fails" +- MEDIUM: item supports the plan but alternatives exist with low switching cost + (e.g., utility libraries, secondary patterns, testing tools) + Rationale example: "MEDIUM — YamlDotNet parses config; could swap to SharpYaml + with ~2 days of work if needed" +- LOW: item is standard practice or dev tooling with no plan-specific risk + (e.g., linters, formatters, common build tools) + +Each entry must include a one-line rationale justifying its impact level. +This prevents gaming: downgrading a critical dependency to MEDIUM to avoid +source verification requirements is visible and reviewable. + +SOURCE CREDIBILITY (required for HIGH-impact entries): +Every "Who uses it at scale" and "Industry evidence" claim must be backed by +a verifiable source. Do NOT fabricate company examples. + +Source tiers: +- TIER A (preferred): Official docs, conference talks with video/slides, + published case studies, peer-reviewed papers, DORA/ThoughtWorks reports +- TIER B (acceptable): Reputable blog posts (company engineering blogs), + GitHub repos with usage evidence, Stack Overflow answers with high votes +- TIER C (flag): Training data recall without a specific URL — mark these as + "[UNVERIFIED — common knowledge, no primary source found]" so the reader + knows the claim needs manual verification + +HIGH-impact entries MUST have at least one TIER A or TIER B source. +If no verifiable source can be found for a HIGH-impact claim, flag it: +"[SOURCE NEEDED — this claim requires manual verification before scope lock]" + +URL VERIFICATION: When ref_read_url, web_search_exa, WebSearch, or WebFetch +tools are available, verify that reference URLs for HIGH-impact entries are +reachable before writing them. +- Prefer ref_read_url for documentation URLs (returns clean markdown, trajectory-aware) +- Use web_search_exa for general web URLs (semantic matching) +- Fall back to WebFetch if MCP tools are not available +If a URL is dead or redirects to unrelated content, downgrade to TIER C and +flag as "[LINK DEAD — needs replacement source]". + +CONFLICTING EVIDENCE: If two sources disagree on a claim (e.g., one recommends +a tool, another warns against it), document both perspectives: +"[CONFLICTING] Source A says X. Source B says Y. This plan assumes X because +{rationale}." Let the stakeholder see the tension rather than hiding it. + +CONFIDENCE FALSIFICATION (post-scope-lock): +If a confidence entry is later found to be wrong (e.g., a tool doesn't support +a claimed feature, a company example was fabricated, a pattern doesn't apply): +1. Create a Change Record (CR-{N}) documenting what was wrong and the impact +2. Mark the confidence.md entry with: "**FALSIFIED ({date}):** {what was wrong}" +3. Mark downstream artifacts that relied on this claim as WARNING in status.json +4. If the falsified claim was HIGH-impact, trigger a scope review (return to Phase 3) +5. If Build phase is in progress, freeze any tickets that depend on the falsified + claim until the scope review completes + +ANCHOR IDS: +Each entry heading must include a kebab-case anchor for cross-plan linking: +`### YamlDotNet 16.3.0 {#yamldotnet-16}` so other plans can link directly. +When searching for cross-plan references, search for both the tool/pattern +name AND common aliases (e.g., "YAML" for "YamlDotNet", "strangler" for +"strangler fig pattern"). + +GATE: User confirmation REQUIRED. +"Does this scope look right? [confirm / adjust / back to research]" + +On "adjust" -> iterate on the approach. +On "back to research" -> return to Phase 2 (mark research stale if scope changed). + +Update status.json, manifest.md. diff --git a/plugins/deepgrade/skills/plan/phases/phase-4-plan.md b/plugins/deepgrade/skills/plan/phases/phase-4-plan.md new file mode 100644 index 0000000..678cc92 --- /dev/null +++ b/plugins/deepgrade/skills/plan/phases/phase-4-plan.md @@ -0,0 +1,58 @@ +# Phase 4: PLAN + +Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. + +Question: How will we execute? + +Create docs/specs/{plan-name}.md with THREE views: + +1. JIRA-READY TICKETS: Per phase, with title, acceptance criteria, assignable +2. LEADERSHIP SUMMARY: Executive summary, timeline table, go/no-go criteria +3. WORKING CHECKLIST: Step-by-step with verification per step + +Detail level per phase based on risk: +- HIGH risk: exact files, function names, grep patterns, commit SHA, test requirements +- MEDIUM risk: file paths, approach, key decisions +- LOW risk: goals, scope, success criteria + +Include: +- Timeline table with dependencies and critical path +- Operational readiness section (if deployment involved): monitoring, config rollout, incident fallback, success metrics +- Rollback plan per phase +- Go/no-go criteria per phase boundary + +TESTING METHODOLOGY SELECTION (REQUIRED): +For EACH deliverable in the spec, select the appropriate testing methodology. +Do NOT default to "unit tests" for everything. Reference the Testing Methodology +Selection Framework (docs/planning-techniques/10-testing-methodology-selection.md). + +| # | Methodology | Evidence Tier | When to Use | +|---|-------------|--------------|-------------| +| 1 | TDD | ENTERPRISE-VALIDATED | New feature with clear spec, algorithms, core business logic, stored procedures | +| 2 | BDD | INDUSTRY-RECOMMENDED | User-facing features, cross-functional teams, requirements ambiguity | +| 3 | Characterization / Golden Master | ENTERPRISE-VALIDATED | Refactoring legacy code, extracting from monolith, data migration validation | +| 4 | Contract Testing | INDUSTRY-RECOMMENDED | Microservices, API integrations, database backward compatibility | +| 5 | Property-Based | INDUSTRY-RECOMMENDED | Algorithms with infinite input space, financial calculations, query performance | +| 6 | Snapshot / Approval | INDUSTRY-RECOMMENDED | UI components, serialized output, reports, config generation | +| 7 | Shadow / Parallel | ENTERPRISE-VALIDATED | Production migration, database cutover, replacing live systems | +| 8 | ATDD | INDUSTRY-RECOMMENDED | Sprint planning, user story definition, database migration sign-off | +| 9 | Mutation Testing | EMERGING PRACTICE | Pre-release quality gate, measuring test suite effectiveness | +| 10 | Exploratory | ENTERPRISE-VALIDATED | Complex UI, late-stage discovery, automation gaps | +| 11 | Expand/Contract | ENTERPRISE-VALIDATED | Database schema migration, renaming columns/tables, changing data types | + +AI-specific requirements: +- The agent that writes implementation code MUST NOT write the tests (Separate Test Authorship) +- AI-generated code receives higher testing scrutiny than human code +- Every AI-generated deliverable is checked against the AI Failure Mode Checklist: + logic drift, stale dependencies, hidden business rule violations, tautological + tests, happy-path-only coverage + +For database schema changes, use Expand/Contract (Methodology 11) with three phases: + - Expand: add new alongside old (structural assertions) + - Migrate: dual-write, backfill, test (data integrity + shadow comparison) + - Contract: remove old after cutover (no orphan references) + +GATE: User confirmation REQUIRED. +"Plan created with {N} phases and {M} tickets over {X} weeks. Review and confirm?" + +Update status.json, manifest.md. diff --git a/plugins/deepgrade/skills/plan/phases/phase-5-audit.md b/plugins/deepgrade/skills/plan/phases/phase-5-audit.md new file mode 100644 index 0000000..c90c0cc --- /dev/null +++ b/plugins/deepgrade/skills/plan/phases/phase-5-audit.md @@ -0,0 +1,565 @@ +# Phase 5: AUDIT + +Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. + +## Contents + +- Checks 1-4: score, devil's advocate, codebase verification, gap verification +- Outputs A-D: coverage matrix, assumption register, scenario matrix, cross-cutting sweep +- Canary (run before the auditor is spawned) +- Evidence validation +- Infrastructure verification +- Plan lint rules and gap summary +- Confidence reinforcement +- Baseline snapshot and score distribution +- Gate: evaluator-optimizer loop, rubric-free pass, gate expression +- Revision feedback and auditor isolation +- Human review gate and waiver condition + +Question: What is weak or missing? + +Run four checks using the plan-auditor agent: + +CHECK 1 - 8-DIMENSION SCORE: +The rubric, its per-level anchors and the band interpretation live in +`agents/plan-auditor.md`. They are deliberately not repeated here. + +This file is read by the Phase 4 generator. A generator that can see the scoring +function writes to the scoring function — it produces text shaped like each anchor +rather than a plan that happens to score well, and the two are indistinguishable +from the score alone. Keeping the rubric on the auditor's side is what makes the +score a measurement of the plan rather than a measurement of how well the generator +remembered the rubric. + +The score is reported. Under the verifier-first gate it does not authorize passage +(see GATE below), so its role is trend and triage, not permission. + +CHECK 2 - DEVIL'S ADVOCATE: +Challenge each assumption. For each challenge, cite evidence or flag [VERIFY]. +Structured premortem questions: + "If this fails in production, what is the most likely reason?" + "What did we assume would be true but isn't?" + "What changed in one layer but not another?" + "What behavior works in tests but fails in browser/runtime?" + +CHECK 3 - CODEBASE VERIFICATION: +Confirm file paths, line numbers, function names referenced in plan actually exist. + +CHECK 4 - GAP VERIFICATION (new): +This check produces 4 structured outputs that catch systematic gaps. +A plan CANNOT be considered gap-checked until all 4 outputs exist. + +OUTPUT A: Coverage Matrix +Map every goal, risk, dependency, and non-goal to its plan artifact: + +```markdown +## A. Coverage Matrix + +| Item | Type | Covered By | Status | +|------|------|-----------|--------| +| bilingual receipts | goal | Phase 1, POS-5163, tests T1/T2 | covered | +| certification timeline | dependency | Phase 4, owner TBD | partial | +| rollback | operational | plan section + handoff | covered | +| CORS handling | non-goal | explicitly excluded | ok-excluded | +| user pagination | assumption | not addressed | GAP | +``` + +Rules: +- Every goal must map to at least one phase AND at least one ticket +- Every risk must map to a mitigation +- Every dependency must map to an owner or blocker +- Every rollout item must map to monitoring + rollback +- Every non-goal must NOT accidentally appear in the plan +- Items marked GAP fail the gap check + +OUTPUT B: Assumption Register +Every assumption the plan makes, with impact-if-false and verification: + +```markdown +## B. Assumption Register + +| # | Assumption | Impact If False | How to Verify | By When | Owner | Status | +|---|-----------|----------------|---------------|---------|-------|--------| +| 1 | User lookup fits in first page | Breaks onboarding flow | Check query with production data volume | Before Phase 2 | Kyle | unverified | +| 2 | triPOS SDK supports Canada | Blocks entire plan | Test API call to Canadian endpoint | Phase 1 | Kyle | verified | +| 3 | Supabase rate limit handles OTP volume | Throttles users at scale | Load test 100 concurrent OTPs | Before launch | TBD | unverified | +``` + +Rules: +- Every assumption must have an impact assessment +- Unverified high-impact assumptions are BLOCKERS +- Assumptions with no validation step are WARNINGS +- Assumptions that block execution must be verified before Build phase + +AUTOMATED ASSUMPTION VERIFICATION: +After generating the Assumption Register, attempt automated verification +of all assumptions that have a verification method: + +For each assumption where impact = HIGH and status = unverified: + 1. If verification method mentions file/path: run `test -f [path]` + 2. If verification method mentions API/endpoint: note as REQUIRES_MANUAL + 3. If verification method mentions schema/database: search for schema files + 4. If verification method mentions config: search config files + 5. Update assumption status in status.json: + - verified: automated check passed + - unverified: automated check failed or not automatable + - falsified: automated check proved assumption false + +Track verification results: + "Assumptions: X total, Y verified (Z automated, W manual), V unverified, F falsified" + +OUTPUT C: Scenario Matrix +The auditor maps a fixed set of scenarios to implementation, test and monitoring. +The scenario list and the output table live in `agents/plan-auditor.md`; they are +not repeated here, for the same reason the rubric is not. + +What the plan itself must do — state this to the generator, not the list: +the plan has to account for how the change behaves when it works, when it fails, +while old and new run side by side, under load, at permission boundaries, across +environment differences, and on the way back out. A plan written against a named +checklist tends to grow a section per checklist item; a plan written against the +requirement tends to notice which of those actually apply to it and say so. + +Every scenario in the auditor's set gets an entry, including "not applicable" with +a reason. Items marked GAP fail the gap check. + +OUTPUT D: Cross-Cutting Concern Sweep +The auditor checks every feature and change against a fixed set of concerns. That +set and its output table live in `agents/plan-auditor.md` and are not repeated here. + +What the plan itself must do: address the concerns that cut across the change +rather than sitting inside one component — the contract it exposes, who is allowed +to call it, what differs between environments, how it behaves at the network and +data-access boundary, what it emits when running, and how it migrates and rolls +back. Concerns that genuinely do not apply are excluded explicitly with a reason. + +Every concern in the auditor's set gets a verdict. Unaddressed concerns are GAPS; +partial ones are WARNINGS. + +CANARY (automated, run BEFORE the auditor is spawned): + +Every other check in Phase 5 examines the plan. This one examines the auditor. + +```bash +node "${CLAUDE_PLUGIN_ROOT}/scripts/dg-canary.js" inject \ + docs/specs/{plan-name}.md docs/plans/{date}-{plan-name}/.canary/ +``` + +One known defect is injected into a working copy of the spec — a rollback line +removed, a dependency owner blanked, an unverified HIGH-impact assumption added, +go/no-go criteria deleted, or a claim of coverage from a test file that does not +exist. The class is recorded along with the single criterion it violates. + +The auditor then audits the MUTATED copy, knowing nothing of any of this. + +Afterwards: + 1. If the recorded criterion is NOT in the audit's UNMET set, the audit missed a + defect that was placed there to be found. Re-run once with a different class. + A second miss fails the gate as "audit untrustworthy" — and DOES NOT trigger + the revision loop. Revising a plan against findings from an audit that could + not see a planted defect is worse than not revising: it rewrites the spec to + satisfy conclusions never derived from reading it. + 2. If it was found, strip that finding from the report — it is an artefact of + this harness, not a property of the plan — and then RE-CHECK that one + criterion against the unmutated original. The strip alone is unsafe: if the + plan has a genuine gap on the same criterion, removing "the LINT-03 finding" + would remove the real one with it. The strip removes the artefact; the + recheck decides the truth. + +An audit reporting zero gaps on a document known to contain a defect is not a +clean audit. It is a broken one, and nothing in its output would tell you so. + +Known limitation, stated rather than glossed: the auditor can read +`scripts/dg-canary.js`, including its defect table. This detects a lazy audit +reliably and an adversarial one only incidentally. Rotating the class per run +raises the cost of pre-empting it; it does not make the canary tamper-proof. + +EVIDENCE VALIDATION (automated, run before anything is treated as MET): + +The auditor returns criterion records, each carrying its evidence. Those records are +a PROPOSAL, not a result. Re-check every one of them mechanically: + +```bash +node "${CLAUDE_PLUGIN_ROOT}/scripts/dg-evidence-validate.js" \ + docs/plans/{date}-{plan-name}/evidence/ +``` + +The validator re-reads each cited artifact, confirms its hash still matches, slices +the cited line range and asserts the quoted text is byte-identical to it. It can only +ever DEMOTE a verdict — there is no input that makes it turn an UNMET into a MET. Use +the verdicts it returns, never the verdicts the auditor claimed. + +A record comes back UNMET, with a flag naming the reason, when: + EVIDENCE-INVALID the quote does not match the lines it cites + EVIDENCE-MISSING MET was claimed with no evidence at all + EVIDENCE-STALE the artifact changed after the record was written + EVIDENCE-ARTIFACT-MISSING the cited file does not exist + EVIDENCE-RANGE-INVALID the cited line range does not exist in the file + EVIDENCE-UNEXECUTED an executable criterion retained no command + EVIDENCE-COMMAND-FAILED the retained command exited non-zero + +The fourth rule is the one that matters most and is easiest to soften by accident: +an externally checkable claim with no evidence is UNMET. Not PARTIAL, not a warning, +not "verified but undocumented". This project has lost that argument twice — a layer +was recorded PARTIAL with its result asserted in a commit message and no artifact in +any commit, and a whole wave was closed against greps typed at a terminal that left +nothing behind. Both are UNMET here without anyone needing to notice. + +Do not re-run the auditor to "resolve" a demotion. A demotion is not a disagreement +to be settled; it means the evidence was not there, and the fix is in the plan. + +COMMIT the evidence directory together with audit.md. An audit whose evidence is not committed did not happen. + +This is the rule that makes an audit auditable later. A verdict is only as good as +the ability to re-derive it, and a re-check needs the records, the artifacts and the +hashes that bound them together at the time. Without them the audit degrades into +testimony — "it passed when I ran it" — which is exactly the class of claim this +project has already had to refuse twice. + +Exit codes from the validator, which the gate branches on: + 0 every record survived re-checking + 1 at least one claimed MET was demoted — the gate does NOT open + 2 the evidence directory is missing or empty + +Treat 2 as the most serious of the three. A missing directory is not a clean run +with nothing to report; it means the audit produced no evidence at all, and reading +it as a pass would rebuild the exact failure this replaces — a phase recorded green +on the strength of a claim that no artifact anywhere supports. + +INFRASTRUCTURE VERIFICATION (automated, run after gap matrices): +Cross-reference every coverage claim against verifiable artifacts. + +For each Scenario Matrix "Tested?" entry with a test file reference: + 1. Check if the test file exists: `test -f "$TEST_PATH"` + 2. If file exists, check it contains a relevant test: `grep -c "$SCENARIO_KEYWORD" "$TEST_PATH"` + 3. If file missing or no matching test: flag as INFRA-GAP + +For each Scenario Matrix "Monitored?" entry with a monitoring reference: + 1. Search for dashboard configs, alert rules, or monitoring setup files + 2. If monitoring config missing: flag as INFRA-GAP + +For each Coverage Matrix "Covered By" entry with a file reference: + 1. Verify the referenced file exists and contains relevant implementation + 2. If file missing or no matching implementation: flag as INFRA-GAP + +INFRA-GAP is a distinct severity: the plan CLAIMS coverage but the +infrastructure to deliver that coverage does not exist. This is more +dangerous than a known gap because it creates false confidence. + +Report: "Infrastructure Verification: X/Y claims verified (Z% rate)" +List all INFRA-GAPs with the claim, expected file, and actual status. + +PLAN LINT RULES (automated, run before presenting results): +These are binary pass/fail checks. Any FAIL is a gap. + +Rule text and the applicable rule set live in `docs/planning-techniques/lint-registry.md`. +Read it and apply every rule the registry assigns to Phase 5 in the current audit mode. +This file names ids only — it does not restate what a rule means, so the two cannot +drift apart. Report one PASS/FAIL per id, using the ids exactly as the registry +numbers them. + +Apply at Phase 5: the registry's Phase 5 set. +LINT-14 is skipped on the first audit (no baseline exists to regress from). +LINT-11 and LINT-12 belong to Phase 7 and do not run here. + +GAP SUMMARY: +After all 4 outputs + lint rules, produce: + +```markdown +## Gap Summary + +Lint: {N}/{applicable} passed, {M} failed <- denominator = the registry's Phase 5 set for this mode +Coverage Matrix: {N} items, {M} gaps +Assumption Register: {N} assumptions, {M} unverified high-impact +Scenario Matrix: 8 scenarios, {M} gaps +Cross-Cutting Sweep: {N} concerns, {M} gaps + +Total gaps: {sum} +Total warnings: {sum} + +Gap-checked: YES / NO +``` + +A plan is gap-checked ONLY when: +- Every rule in the registry's Phase 5 set passes (enumerating a subset here is how + the count drifted to four different values before PH5-001) +- Coverage matrix has zero GAPs +- No unverified HIGH-impact assumptions +- Scenario matrix has zero GAPs +- Cross-cutting sweep has zero GAPs +- Infrastructure verification has zero INFRA-GAPs + +Write docs/plans/{date}-{plan-name}/audit.md with: scored dimensions, challenges, verification results, ALL 4 gap verification outputs, lint results, gap summary. + +Update manifest.md: add audit.md to Plan Files table with date and score. + +CONFIDENCE REINFORCEMENT (after audit, before baseline): + +Re-read confidence.md (created in Phase 3) and reinforce it with audit findings: + +1. AUDIT-DRIVEN ADDITIONS: + - If the audit identified new dependencies, patterns, or tools not in the + original confidence.md (e.g., from gap-filling revisions), add entries. + - If the audit challenged an assumption about a tool/method and the + challenge was resolved, add a "Validated by audit" note to that entry. + +2. STRESS-TEST ANNOTATIONS: + For entries where the audit found weakness or gaps, add a subsection: + ```markdown + **Audit note ({date}):** {What the audit found — e.g., "Devil's advocate + challenged whether YamlDotNet handles multi-document streams. Verified: + YamlDotNet 16.x supports multi-doc via `LoadStream()`. No gap."} + ``` + For entries where audit found a real gap, note the gap AND how it was resolved: + ```markdown + **Audit note ({date}):** {Gap found and resolution — e.g., "Audit flagged + missing error handling for malformed YAML. Added try/catch in Phase 5 + revision v2. Gap closed."} + ``` + +3. UPDATE HEADER: + Set "Last reinforced: {date} (Phase 5)" in the confidence.md header. + +4. NEW CROSS-PLAN REFERENCES: + If the audit revision introduced tools/patterns that exist in other plans, + add "Also referenced in" links. + +Update manifest.md: update Confidence row with reinforcement date. + +BASELINE SNAPSHOT: +After writing the audit, capture a per-element baseline in status.json: +```json +{ + "baseline": { + "run_number": 1, + "date": "{ISO date}", + "plan_version": "v1", + "lint_results": { "LINT-01": "pass", "LINT-02": "pass", ... }, + "coverage_items": [{ "name": "...", "status": "covered|gap" }], + "assumption_counts": { "total": N, "verified": N, "unverified": N, "waived": N }, + "scenario_statuses": [{ "id": 1, "name": "Happy path", "status": "covered|partial|gap" }], + "concern_statuses": [{ "name": "API contract", "status": "ok|warn|gap" }], + "dimension_scores": [{ "name": "Problem Definition", "score": 4 }], + "infra_gaps": N + } +} +``` + +On re-audit (after revision loop or manual re-run), compare current vs baseline: +- REGRESSION: item was covered/passing, now gap/failing -> flag in audit output +- IMPROVEMENT: item was gap/failing, now covered/passing -> report as progress +- NEW: item not in previous baseline -> report for awareness + +Report: "Baseline comparison: X regressions, Y improvements, Z new items" +Regressions are flagged as HIGH priority in the audit output. + +This comparison is what LINT-14 is evaluated against (see the registry for its text). +Only an element that was covered/passing in the previous baseline and is now +gap/failing counts; pre-existing gaps do not trigger it. Skipped on the first audit, +when no baseline exists. + +Update the baseline in status.json after each comparison (append to history array +for trend tracking). + +SCORE DISTRIBUTION (append on every audit, including re-audits): + +Record each audit's score in a score_history array in status.json: +```json +{ + "score_history": [ + { "date": "{ISO date}", "plan_version": "v1", "iteration": 1, + "score": 27, "canary_found": true, "gate_passed": false }, + { "date": "{ISO date}", "plan_version": "v2", "iteration": 2, + "score": 36, "canary_found": true, "gate_passed": true } + ] +} +``` + +The score no longer gates, but its distribution is still the cheapest detector of +the gate being gamed. A cluster of totals sitting just above any historical +threshold — 32-34 under the old regime — is the statistical signature of +threshold-aiming, and it is visible only as a series. One audit's score means +almost nothing; forty audits piling up at the same boundary means the boundary is +being aimed at. Keeping the series costs one array append. + +GATE: Evaluator-Optimizer Loop. + +RUBRIC-FREE HOLISTIC PASS (advisory, runs alongside the gate): + +RUN one additional judge with no rubric, no criterion list, and no dimension names. + +Its entire prompt is: "Ignore any checklist. What would make this plan fail in +production?" Fresh instance, same input manifest as the auditor, none of the +criterion files. + +Map its findings against the criterion set afterwards. A finding that maps to an +existing criterion is discarded — the gate already covers it. A finding that maps +to NOTHING is appended to docs/planning-techniques/lint-candidates.md with the plan +name and date, as a candidate rule for owner review. + +This pass never gates, and that is deliberate. Every other mechanism in Phase 5 +makes the judge honest ABOUT the criteria; none of them can notice that the +criteria are incomplete. A plan can satisfy every rule and still be bad in a way no +rule names — rubric-design failure as distinct from verifier failure. This is the +only check on that class, and its output is a proposed rule, not a verdict on the +current plan: gating on unmapped findings would just re-create the unfalsifiable +prose judgment the gate rewrite removed. + +The gate does not read the score. It reads whether the claims survived checking. + + +CANARY_OK = the criterion the planted defect violates came back UNMET +EVIDENCE_OK = dg-evidence-validate.js exited 0 (nothing was demoted) +VERIFIED = every applicable criterion is MET or N_A after validation +INFRA_OK = infra_gaps == 0 + +PASS = CANARY_OK AND EVIDENCE_OK AND VERIFIED AND INFRA_OK + + +Every term is re-derivable by someone who has the plan folder and did not run the +audit. That is the property being bought here: the previous gate authorised passage +on a number the audited model chose for itself, and no reader could tell a plan that +earned it from one that was written to earn it. + +There is no weighted sum, so a strong showing on seven criteria cannot offset a +failure on the eighth. Non-compensability is the thing a 40-point total structurally +cannot give you. + +IF PASS: + -> "Plan is solid. Ready to start building." + -> Proceed to Phase 6. + +IF NOT PASS: + -> If CANARY_OK is false after a re-run: STOP. Do not revise. The audit could not + see a defect placed for it to find, so its other findings are not a basis for + rewriting anything. + -> Otherwise auto-trigger revision of the Phase 4 spec, using the feedback form + below. + -> Revise ONLY the failing sections (not the entire spec). + -> Re-run the audit on the revised spec. + -> Compare re-audit against baseline: flag any regressions (items that + were passing in v1 but now fail in v2). Regressions indicate the + revision broke something that was previously working. + -> Maximum 2 revision iterations. + + +Send the generator defects and locations. One line per unmet criterion: + + {criterion_id} UNMET: {what is missing}. Location: {file}:{line}. + +Worked example: + + LINT-03 UNMET: Phase 2 database migration has no rollback step. + Location: docs/specs/plugin-hardening-v5.md:142. + +Never send the rubric, the totals, the bands, or how near the plan came to passing. +The generator cannot see any of that when it writes, and returning it through the +revision channel would hand back exactly what was withheld — after which the cheapest +response is prose shaped like the missing thing rather than the missing thing itself. + +A defect the generator can locate is a defect it can fix. A number it can chase is a +number it will chase. + + +SPAWN A NEW plan-auditor INSTANCE for every audit iteration. Do not re-audit inside +the instance that produced the previous verdict, and do not pass it the previous +audit.md, the previous score, or a summary of either. + +An evaluator that already published a number for v1 is, on v2, checking its own +prior judgement. The consistent story available to it is that the revision fixed +what it said was broken, so the second audit tends to ratify the first rather than +re-derive it — and the loop's regression check is exactly the thing that cannot +work if the same evaluator grades both sides of it. The agent refuses prior-iteration +scores on its side too (see in agents/plan-auditor.md); both +halves are required, because either alone is a single point of failure. + +The baseline comparison above is done by the CALLER, which holds both audits. The +judge sees one spec and reports on it, and never learns that a previous attempt +existed. + +After revision loop completes, report against the gate, not against a band: +- PASS: "Plan revised and now solid. Ready to build." +- NOT PASS, criteria still unmet after 2 iterations: "Plan has remaining unmet + criteria. Fix manually: [list each id with its defect and location]" +- NOT PASS because evidence was demoted: "Claims in this plan are not supported by + what they cite: [list each flag]. These are not near-misses; the cited text does + not say what the plan says it says." +- NOT PASS because the canary was missed twice: "The audit could not be trusted and + no revision was attempted. Re-run Phase 5 before reading any of its findings." + +A plan does not "usably pass with known gaps". Either every applicable criterion is +satisfied and evidenced, or the specific ones that are not get named. The old +YELLOW rung existed because a 24-31 total had to mean something; without the total +there is nothing for it to mean, and "proceed with known gaps" was the rung most +often used to proceed without reading them. + +Track revision history in audit.md: +```markdown +## Revision History +| Version | Score | Gap-Checked | Gaps | Action | +|---------|-------|-------------|------|--------| +| v1 | 24/40 | NO | 7 | Auto-revised sections 4, 5, 7 | +| v2 | 35/40 | YES | 0 | Accepted | +``` + +Update status.json (include score, rating, gap_checked boolean, gap_count), manifest.md. + +HUMAN REVIEW GATE (conditionally waivable): +After the automated audit completes, prompt for human review before Build: + +"Automated audit complete (score: {X}/40, gap-checked: {YES/NO}). + Before starting Build, this plan should be reviewed by at least one person. + [1] Enter reviewer name(s) to proceed + [2] Waive review (solo mode) — requires documented reason, and only offered + when the waiver condition below holds + [3] View audit summary first" + + +waiver_allowed = (infra_gaps == 0) + AND (score >= 35) + AND (canary_found == true) + + +This is the one place the score is load-bearing, and the asymmetry is the design: +the score cannot let a plan PASS the gate, but a borderline one can remove the +owner's ability to SKIP review. A gameable signal is safe in the direction that +adds friction. The 32-34 band — the scores that sat just above the old threshold — +is exactly where threshold-aiming lands, so a plan scoring there gets a human +whether or not the automated gate passed. + +If the waiver condition fails, option [2] is not offered at all. Do not present it +greyed out with the reason; a visible near-miss invites one more revision aimed at +the waiver rather than at the plan. + +If [1]: Record reviewer name(s) and date in status.json: + { "review": { "reviewers": [{"name": "...", "date": "..."}], "outcome": "accepted" } } + Proceed to Phase 6. + +If [2]: Record waiver in status.json AND stamp it visibly: + { "review": { "waived": true, "reason": "...", "waived_by": "...", + "waiver_condition": { "infra_gaps": 0, "score": X, "canary_found": true } } } + Also append one line to audit.md and to the Phase 9 handoff: + "Review waived (solo mode) by {name} on {date}: {reason}" + A waiver recorded only in machine state is invisible to the person reading the + plan later, which is the person it exists to warn. Proceed to Phase 6. + +If [3]: Show audit-derived review checklist: + - Audit scorecard (8 dimensions with scores) + - Top 3 gaps identified + - Top 5 risks identified + - Key assumptions and their verification status + - Cross-cutting concerns flagged as partially addressed + Then re-prompt [1] or [2]. + +If [1] with reviewer names: Record review in status.json: + { "review": { + "reviewers": [{"name": "...", "date": "...", "decision": "accepted"}], + "outcome": "accepted", + "checklist_presented": true, + "comments": 0 + }} + +For team/leadership plans: review is REQUIRED (option [2] not offered unless +the plan was started in solo mode or the user explicitly requests solo mode). + +For solo mode: review is recommended but waivable with documented reason. diff --git a/plugins/deepgrade/skills/plan/phases/phase-6-build.md b/plugins/deepgrade/skills/plan/phases/phase-6-build.md new file mode 100644 index 0000000..759d907 --- /dev/null +++ b/plugins/deepgrade/skills/plan/phases/phase-6-build.md @@ -0,0 +1,122 @@ +# Phase 6: BUILD + +Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. + +## Contents + +- Hard gate: assumption verification (LINT-08) +- Parallel execution rule +- Document actions and codebase actions +- Change control and change record template + +Question: What got built/changed? + +HARD GATE: ASSUMPTION VERIFICATION (LINT-08) +Before ANY build work begins, check assumptions in status.json: + +``` +For each assumption where impact = HIGH: + If status = unverified: + -> BLOCK entry to Phase 6 + -> Present: "Cannot start Build. These HIGH-impact assumptions are unverified:" + -> List each with its verification method + -> Offer: [1] Verify now [2] Accept risk (waiver) [3] Back to research + + If status = verified: -> PASS + If status = waived: -> PASS (with documented risk acceptance) + If status = falsified: -> BLOCK and return to Phase 3 (approach is invalid) + +For each assumption where impact = MEDIUM and status = unverified: + -> WARN but allow proceeding + +For each assumption where impact = LOW and status = unverified: + -> INFO only +``` + +If user chooses [2] Accept risk (waiver), require: +- Documented risk statement +- Approver name +- Contingency plan if assumption fails +- Update assumption status to "waived" in status.json + +This gate is NOT advisory. It is a hard block. The plan CANNOT proceed to +Build with unverified HIGH-impact assumptions unless explicitly waived. + +This phase actively assists with implementation. + +PARALLEL EXECUTION RULE: +Before starting tickets, analyze the dependency graph from the plan: +- Tickets with NO dependencies on other tickets can run IN PARALLEL as subagents +- Tickets that depend on other tickets must wait until dependencies complete +- Group independent tickets into parallel batches + +``` +Example dependency graph: + POS-5160 (no deps) -> Batch 1 (parallel) + POS-5161 (no deps) -> Batch 1 (parallel) + POS-5162 (no deps) -> Batch 1 (parallel) + POS-5163 (needs 5160) -> Batch 2 (after 5160 completes) + POS-5164 (needs 5162) -> Batch 2 (after 5162 completes) + POS-5165 (needs 5163, 5164) -> Batch 3 (after Batch 2) +``` + +Present the batch plan to the user: +"I can run {N} tickets in parallel (Batch 1: {tickets}). +Batch 2 ({tickets}) depends on Batch 1. Execute Batch 1 in parallel? [Y/n]" + +For each parallel batch, deploy subagents: +- Each subagent gets: ticket description, relevant plan sections, codebase context +- Each subagent writes to a separate branch or file set +- Orchestrator tracks progress and resolves conflicts between parallel work + +DOCUMENT ACTIONS (no approval needed): +- Track ticket progress (update status.json with per-ticket notes) +- Answer questions about the plan ("what file for POS-5162?") +- Provide code context from research +- Suggest next ticket to work on based on dependencies + +CODEBASE ACTIONS (approval required per action): +- "Generate code scaffold for CcReceiptStrings.cs? [Y/n]" +- "Run characterization tests on Printing.FormatReceipt? [Y/n]" +- "Create branch description for Phase 1 tickets? [Y/n]" + +CHANGE CONTROL (backward flow rules with immutable records): +After Phase 3 scope lock, accepted plan documents are immutable. Changes +require a formal Change Record, not silent edits. + +- Minor discovery during build: + 1. Create docs/plans/{date}-{name}/changes/CR-{N}.md with: + - What changed and why + - Which document/section it supersedes + - The NEW content (the CR is the authoritative version going forward) + - Impact on other phases + 2. Add a status line to the TOP of the original document: "SUPERSEDED by CR-{N} on {date}" + Do NOT modify the original document's content. The CR contains the new version. + 3. Update manifest.md with link to the Change Record + 4. Update status.json: { "change_records": [{ "id": "CR-001", "date": "...", "summary": "..." }] } + +- Scope change discovered -> "This changes the scope. Go back to Pre-Plan? [Y/n]" + If yes: create CR-{N} documenting the scope change reason, mark pre_plan + and plan as STALE, return to Phase 3. Original approach.md preserved. + +- New blocker found -> mark current build ticket as BLOCKED with reason, + create CR-{N} documenting the blocker and its impact. + +- Implementation diverges from plan -> create CR-{N} documenting the divergence + and rationale. This replaces informal ADR/change notes. + +Change Record template: +```markdown +# CR-{N}: {Title} +Date: {date} +Author: {name} +Supersedes: {document or section} + +## What Changed +## Why It Changed +## Impact on Other Phases +``` + +Update status.json with build progress, manifest.md. + +No gate. User stays in Build until ready for Impact Review. diff --git a/plugins/deepgrade/skills/plan/phases/phase-7-impact-review.md b/plugins/deepgrade/skills/plan/phases/phase-7-impact-review.md new file mode 100644 index 0000000..4b8df56 --- /dev/null +++ b/plugins/deepgrade/skills/plan/phases/phase-7-impact-review.md @@ -0,0 +1,205 @@ +# Phase 7: IMPACT REVIEW + +Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. + +## Contents + +- What it checks: dimensions 1-7 +- Process: parallel subagents +- Output: impact-review.md template +- Testing methodology verification +- Gate + +Question: What else does this change affect across layers? + +This is a cross-cutting verification gate. Code that works locally and passes +targeted tests can still break integration edges, scale behavior, transition-state +UX, and downstream consumers. This phase explicitly asks "what did we miss?" + +WHAT IT CHECKS: + +1. INTEGRATION EDGES + - What other modules call the code we changed? + - Did we update all callers, or just the ones we knew about? + - Are there event handlers, webhooks, or async consumers that depend on + the old behavior? + ```bash + # Find all callers of changed functions + grep -rn "{function-name}" --include="*.cs" --include="*.vb" --include="*.ts" \ + . 2>/dev/null | grep -v node_modules | grep -v test + ``` + +2. CROSS-LAYER EFFECTS + - Database: did schema changes affect other queries or stored procedures? + - API: did response format changes break downstream consumers? + - UI: did state changes affect other screens or components? + - Config: did new settings need to be added to all environments? + +3. SCALE AND PERFORMANCE + - Will this change behave differently at production load? + - Did we add queries inside loops? New N+1 patterns? + - Did we add memory-intensive operations without limits? + +4. TRANSITION-STATE BEHAVIOR + - During rollout, old and new code may run simultaneously. + - Feature flags: is the off-state still safe? + - Database migrations: is the schema compatible with both old and new code? + - What happens to in-flight requests during deployment? + +5. TEST DELTA + - What tests existed before vs after? + - Did we add tests for the new behavior? + - Did existing tests need updating and did we miss any? + - Are there integration tests that cover the cross-cutting paths? + +6. STRING PATH REFERENCES (critical for file moves/renames) + If ANY files were moved or renamed during the build phase, scan for stale + string-based path references that don't auto-update. This is a KNOWN gap: + TypeScript/VSCode updates import statements on file move, but does NOT + update string literals. + + Patterns to scan for old file paths: + - vi.mock("old/path") and jest.mock("old/path") + - require("old/path") string arguments + - eslint.config.js ignore arrays + - tsconfig.json paths and includes + - vite.config.ts resolve.alias + - webpack.config.js alias/resolve + - storybook stories globs + - jest.config moduleNameMapper + - package.json scripts that reference file paths + - .env files with path values + - CLAUDE.md or README references to file locations + + ```bash + # For each moved/renamed file, find stale string references + OLD_PATH="{old-file-path-without-extension}" + grep -rn "$OLD_PATH" --include="*.ts" --include="*.tsx" --include="*.js" \ + --include="*.json" --include="*.config.*" --include="*.md" \ + . 2>/dev/null | grep -v node_modules | grep -v ".git/" + ``` + + Any match is a potential stale reference that needs updating. + TypeScript Issue #62835 (open): This is a known gap in all major IDEs. + +7. BACKWARD TRACEABILITY (does every change serve a goal?) + For every file changed during Build, verify the reverse coverage chain: + - Changed file -> Ticket that authorized the change -> Goal it serves + + Orphan detection: + - Files changed with no ticket mapping = SCOPE CREEP (flag) + - Tickets with no changed files = DELIVERY GAP (flag unless explicitly deferred) + + ```bash + # For each changed file, check if it maps to a plan ticket + # Compare git diff file list against ticket-file mapping in status.json + git diff --name-only HEAD~{N}..HEAD | while read FILE; do + grep -q "$FILE" docs/plans/{date}-{name}/status.json || echo "ORPHAN: $FILE" + done + ``` + + Any orphan file must be either: + - Linked to an existing ticket (developer forgot to log it) + - Justified as necessary infrastructure (added to a new ticket) + - Flagged as scope creep for review + + This traceability check is what LINT-11 and LINT-12 are evaluated against; + the registry holds their text and marks both as Phase 7, Full mode only. + +PROCESS: +PARALLELIZATION RULE: The 5 check dimensions are independent. Deploy parallel +subagents for each dimension to speed up the review. + +Deploy up to 3 subagents in parallel (scale to the size of the change): + +SUBAGENT A - Integration & Cross-Layer (Sonnet): +Objective: Find all callers of changed code, check integration edges and cross-layer effects +Tools: Read, Grep, Glob, Bash +Checks: dimensions 1 (Integration Edges) and 2 (Cross-Layer Effects) + +SUBAGENT B - Scale & Transition State (Sonnet): +Objective: Analyze performance impact and transition-state safety +Tools: Read, Grep, Glob +Checks: dimensions 3 (Scale) and 4 (Transition-State) + +SUBAGENT C - Test Delta, String Paths & Backward Trace (Sonnet): +Objective: Compare test coverage before vs after, scan for stale string path references, AND verify backward traceability of all changed files +Tools: Read, Grep, Glob, Bash +Checks: dimensions 5 (Test Delta), 6 (String Path References), and 7 (Backward Traceability) + +Each subagent writes its section to a temp file. Orchestrator synthesizes. + +Steps: +1. Read the build phase's changed files from status.json +2. Deploy subagents with the list of changed files + relevant audit data +3. Each subagent scans for its dimensions +4. Cross-reference with docs/audit/dependency-map.md (if exists) +5. Cross-reference with docs/audit/integration-scan.md (if exists) +6. Synthesize all subagent findings +7. Flag any untested integration path +8. Present findings as a checklist + +OUTPUT: Written to docs/plans/{date}-{plan-name}/impact-review.md with: + +```markdown +# Impact Review: {Plan Name} +Date: {date} +Changed files: {count} +Integration edges checked: {count} + +## Cross-Cutting Findings + +| # | Finding | Severity | File | Checked? | +|---|---------|----------|------|----------| +| 1 | OrderReceipt.tsx also formats receipt strings | HIGH | src/features/orders/ | [VERIFY] | +| 2 | CCApproval.vb has hardcoded receipt text | MEDIUM | POSetcPOS/CreditCard/ | [VERIFY] | +| 3 | Print preview doesn't use new string table | LOW | POSetcPOS/Printer/ | [VERIFY] | + +## Integration Paths Not Covered by Tests +- [list of caller->callee paths that have no test coverage] + +## Scale Concerns +- [any performance-related observations] + +## Transition-State Risks +- [anything that could break during partial rollout] + +## Checklist Before Test Phase +- [ ] All callers of changed functions verified +- [ ] No untested integration paths remaining (or explicitly accepted) +- [ ] Scale behavior reviewed for production load +- [ ] Feature flag off-state tested +- [ ] Database migration compatible with old and new code +- [ ] No orphan code changes (all changes traced to tickets) [LINT-11] +- [ ] No orphan tickets (all tickets have implementation or are deferred) [LINT-12] + +TESTING METHODOLOGY VERIFICATION: +For each deliverable with an assigned testing methodology (from Phase 4): +- [ ] Methodology is appropriate for the type of change (not defaulting to "unit tests") +- [ ] Test authorship is separate from implementation authorship for AI-generated code +- [ ] Database changes use Expand/Contract with forward AND backward migration scripts +- [ ] API changes have contract tests covering old code + new schema AND new code + old schema +- [ ] Characterization tests captured BEFORE refactoring (not after) +- [ ] AI Failure Mode Checklist applied to all AI-generated deliverables + +Database Migration Testing (if applicable): + +| Phase | What to Test | Method | +|-------|-------------|--------| +| Expand | New columns/tables exist, old untouched | Structural assertions | +| Migrate | Row counts, checksums, referential integrity preserved | Characterization + Shadow | +| Contract | Old structures removed, no orphan refs, all code uses new schema | Structural assertions | +| Rollback | Backward migration restores original state | Apply -> verify -> rollback -> verify | +| Backward compat | Old code + new schema works, new code + old schema works | Contract Testing | +| Performance | Queries under threshold, indexes present, no N+1 | Property-Based + Profiling | +``` + +GATE: User confirmation required. +"Impact review complete. {N} cross-cutting findings, {M} untested integration +paths. Review the findings and confirm before proceeding to Test." + +If HIGH severity findings exist: +"HIGH severity: {finding}. This should be addressed before Test phase. +Fix it now, or accept the risk and proceed? [fix / accept with reason]" + +Update status.json, manifest.md. diff --git a/plugins/deepgrade/skills/plan/phases/phase-8-test.md b/plugins/deepgrade/skills/plan/phases/phase-8-test.md new file mode 100644 index 0000000..fe67d6c --- /dev/null +++ b/plugins/deepgrade/skills/plan/phases/phase-8-test.md @@ -0,0 +1,144 @@ +# Phase 8: TEST + +Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. + +## Contents + +- Document actions +- Methodology-specific test procedures +- Codebase actions +- Two-tier verification +- Hard readiness gate + +Question: Does it work safely? + +DOCUMENT ACTIONS (automatic): +Write docs/plans/{date}-{plan-name}/test-plan.md with: +- Per-phase test matrix (test name, type, what it verifies) +- Edge cases prompted by plan context +- Characterization test candidates for changed code +- Each criterion categorized as AUTOMATED or MANUAL (see below) + +METHODOLOGY-SPECIFIC TEST PROCEDURES: +Based on the testing methodology assigned in Phase 4, execute the appropriate +test procedure for each deliverable. Reference the full framework at +docs/planning-techniques/10-testing-methodology-selection.md. + +IF methodology = expand_contract: +Execute all 18 steps of the database migration test checklist: + + EXPAND PHASE: + - [ ] Forward migration script runs cleanly on empty DB + - [ ] Forward migration script runs cleanly on production-like data + - [ ] New columns/tables exist with correct types and constraints + - [ ] Old columns/tables are untouched (no dropped columns, no renamed columns) + - [ ] Old code works against expanded schema (backward compatible) + - [ ] New code works against expanded schema + + MIGRATE PHASE: + - [ ] Dual-write triggers or application-level dual-write is active + - [ ] Backfill of existing data completes without errors + - [ ] Row counts match pre/post migration + - [ ] Checksums match pre/post migration (normalize volatile data) + - [ ] Referential integrity intact (no orphan foreign keys) + - [ ] Shadow comparison of old vs new query results matches + + CONTRACT PHASE: + - [ ] Backward (rollback) migration script restores original state + - [ ] New code works against contracted schema + - [ ] Old structures removed cleanly (no leftover columns/tables) + - [ ] No orphan references to removed columns/tables in codebase + - [ ] Indexes exist on new columns (no missing index regressions) + - [ ] Query performance within acceptable bounds on new schema + +IF methodology = tdd: + - [ ] Test suite generated from spec BEFORE implementation + - [ ] All tests fail initially (Red phase verified) + - [ ] Implementation passes all tests (Green phase) + - [ ] Refactoring does not break tests + +IF methodology = characterization: + - [ ] Golden master baseline captured BEFORE changes + - [ ] Post-change output matches baseline (or divergences explicitly approved) + - [ ] Volatile data normalized before comparison (timestamps, auto-increment IDs) + +IF methodology = contract_testing: + - [ ] Consumer contracts defined + - [ ] Provider verification passes + - [ ] Old code + new schema validated against contracts + - [ ] New code + old schema validated against contracts + +IF methodology = shadow_parallel: + - [ ] Dual-write infrastructure in place + - [ ] Comparison monitoring active + - [ ] Divergence rate below threshold before cutover + +IF methodology = property_based: + - [ ] Invariants defined and documented + - [ ] Input generators cover edge cases + - [ ] All properties hold under generated inputs + +IF methodology = bdd: + - [ ] Gherkin specs written by humans (product/QA) + - [ ] Step definitions wired and passing + - [ ] All Given/When/Then scenarios covered + +IF methodology = snapshot_approval: + - [ ] Snapshots captured and approved by humans + - [ ] No blind snapshot updates (each change reviewed) + +IF methodology = mutation_testing: + - [ ] Mutation testing tool configured and run + - [ ] Mutation score above team-calibrated threshold + - [ ] All surviving mutants reviewed and justified + +CODEBASE ACTIONS (approval required): +- "Generate characterization tests for {function}? [Y/n]" +- "Create test stubs for new code? [Y/n]" + +TWO-TIER VERIFICATION: +Split all success criteria into two categories. Run automated first, +then pause for manual verification. + +TIER 1 — AUTOMATED VERIFICATION (run without human intervention): +- [ ] All critical path tests pass (run test command) +- [ ] TypeScript/code compiles with no errors (run build command) +- [ ] No lint errors in changed files +- [ ] Characterization baseline captured for any refactored code +- [ ] Audit score is GREEN with gap-checked = YES, or YELLOW with gap-checked = YES + +Run all Tier 1 checks. Report results. Then PAUSE: + +``` +Phase 8 — Automated Verification Complete + +Automated checks passed: +- [list each Tier 1 check and its result] + +Ready for manual verification. Please perform these checks: +- [ ] [Manual item 1] +- [ ] [Manual item 2] + +Let me know when manual testing is complete so I can proceed to Handoff. +``` + +TIER 2 — MANUAL VERIFICATION (requires human testing): +- [ ] No open P0/P1 defects against this plan +- [ ] Rollback plan has been validated (tested in staging or reviewed by ops) +- [ ] Key user flows work as expected in staging/preview +- [ ] Edge cases identified in test-plan.md have been manually verified +- [ ] Deployment runbook reviewed by someone other than the author + +Do NOT auto-check Tier 2 items. Wait for human confirmation on each. +Track which items the human confirmed and when: + { "test_gate": { "automated": { "passed": 5, "failed": 0 }, "manual": { "verified": 4, "pending": 1, "verified_by": "J. Smith", "date": "..." } } } + +HARD READINESS GATE: +Before proceeding to Handoff, ALL of these must be true: +- All Tier 1 (automated) checks pass +- All Tier 2 (manual) checks confirmed by a human +- No Tier 2 items left in "pending" state + +If gate fails, report what's missing and stay in Test phase. + +Update status.json, manifest.md. diff --git a/plugins/deepgrade/skills/plan/phases/phase-9-handoff.md b/plugins/deepgrade/skills/plan/phases/phase-9-handoff.md new file mode 100644 index 0000000..42151eb --- /dev/null +++ b/plugins/deepgrade/skills/plan/phases/phase-9-handoff.md @@ -0,0 +1,34 @@ +# Phase 9: HANDOFF + +Phase file for `/deepgrade:plan`. Loaded by `${CLAUDE_SKILL_DIR}/SKILL.md` when the workflow enters this phase. Do not read ahead to other phase files. + +Question: What happens next? + +READINESS CHECK before entering this phase: +- Test phase complete (or explicitly waived) +- Audit score GREEN or YELLOW with gap-checked = YES +- No BLOCKED tickets remaining (or explicitly deferred) +- Rollback plan documented + +Context-aware guidance based on situation: +- If ready to ship: specific deployment sequence with verification steps +- If gaps remain: prioritized list of what to fix with reasoning +- If timeline pressure: critical path items vs deferrable items + +Update manifest.md with final status, decisions made, lessons learned. +Update status.json: handoff -> complete. + +Present final summary: +``` +Plan: {name} - Complete + +Phases: 9/9 +Duration: {started} to {completed} +Audit score: {score}/40 ({rating}) +Tickets: {done}/{total} + +Key decisions: [from approach.md and change records] +Change records: {count} (see changes/ folder) +What shipped: [summary] +What's deferred: [if anything] +``` diff --git a/tests/layer1-core.sh b/tests/layer1-core.sh index 019790d..407603a 100644 --- a/tests/layer1-core.sh +++ b/tests/layer1-core.sh @@ -31,9 +31,9 @@ cd "$PLUGIN_DIR" || { echo "[FAIL] plugin dir '$PLUGIN_DIR' does not exist"; exi # --------------------------------------------------------------------------- case "$PROFILE" in deepgrade) - # Planning core: 9 commands, the two planner agents, 3 skills, the three + # Planning core: 8 commands, the two planner agents, 4 skills, the three # plan-context hooks, and the canary/evidence audit tooling wired from - # commands/plan.md (F06's command-wired mechanism). + # skills/plan/ (F06's command-wired mechanism). PLUGIN_NAME="deepgrade" OWN_NS="deepgrade" EXPECTED_EVENTS="SessionStart SubagentStop PreCompact" @@ -1082,7 +1082,7 @@ allow_of() { } mcp_bad=0 mcp_subjects=0 -for f in "$AGENTS_DIR"/*.md "$COMMANDS_DIR"/*.md; do +for f in "$AGENTS_DIR"/*.md "$COMMANDS_DIR"/*.md "$SKILLS_DIR"/*/SKILL.md; do [ -e "$f" ] || continue val=$(allow_of "$f") [ -z "$val" ] && continue @@ -1248,8 +1248,8 @@ else [ "$missing" -eq 0 ] && pass "F06: every referenced handler script exists" # The plugin invokes scripts by two mechanisms, and F06 originally knew only one. - # Hook handlers are named in hooks.json; audit tooling is invoked from a command or - # agent as an explicit `node .../scripts/NAME` line. The invariant F06 defends is + # Hook handlers are named in hooks.json; audit tooling is invoked from a command, + # skill, or agent as an explicit `node .../scripts/NAME` line. The invariant F06 defends is # "no unwired code ships", not "everything in scripts/ is a hook", so the reverse # sweep accepts either mechanism (PH5-020). # @@ -1258,7 +1258,7 @@ else # followed by the path — keeps this structural. A script named only in a sentence # is still an orphan, which is the correct answer. inv_re='node[^`]*scripts/[A-Za-z0-9._-]+\.js' - inv=$(grep -ohE "$inv_re" commands/*.md agents/*.md 2>/dev/null | sed 's|.*/||' | sort -u) + inv=$(grep -ohE "$inv_re" commands/*.md agents/*.md skills/*/*.md skills/*/phases/*.md 2>/dev/null | sed 's|.*/||' | sort -u) inv_count=$(echo "$inv" | grep -c . || true) # Self-tests. The known-positive is the QUOTED form, copied from how the plugin @@ -1456,8 +1456,8 @@ if [ "$f14_actual" != "$f14_want" ]; then fi # Negative, per the §3.8 discovery-path decision: `plan` must stay model-invocable. if [ "$F14_PLAN_NEG" -eq 1 ]; then - [ -n "$(fm_get "$COMMANDS_DIR/plan.md" 'disable-model-invocation')" ] \ - && { fail "F14: plan.md must NOT disable model invocation (§3.8 discovery path)"; f14_bad=1; } + [ -n "$(fm_get "$SKILLS_DIR/plan/SKILL.md" 'disable-model-invocation')" ] \ + && { fail "F14: skills/plan/SKILL.md must NOT disable model invocation (§3.8 discovery path)"; f14_bad=1; } fi [ "$f14_bad" -eq 0 ] && pass "F14: disable-model-invocation on exactly [$f14_want], not on plan" @@ -1598,7 +1598,7 @@ for d in "$SKILLS_DIR"/*/; do # An explicit ${CLAUDE_PLUGIN_ROOT}/skills// path is accepted too: it is a real, # unambiguous reference, and rejecting it was over-strict (Codex Q3). if ! grep -rhE "$OWN_NS:$sk([^A-Za-z0-9_-]|\$)|skills/$sk/SKILL\.md" \ - "$AGENTS_DIR" "$COMMANDS_DIR" "$SKILLS_DIR"/*/SKILL.md 2>/dev/null \ + "$AGENTS_DIR" "$COMMANDS_DIR" "$SKILLS_DIR"/*/SKILL.md "$SKILLS_DIR"/*/phases/*.md 2>/dev/null \ --exclude-dir="$sk" \ | grep -viE '(never|do not|don'"'"'t|no longer|deprecated|avoid)[^.]{0,60}('"$sk"')' \ | grep -q .; then diff --git a/tests/layer1-repo.sh b/tests/layer1-repo.sh index 94ed699..e15a101 100644 --- a/tests/layer1-repo.sh +++ b/tests/layer1-repo.sh @@ -305,10 +305,10 @@ fi # --- A1a: machine-read files carry ids, never rule text ------------------- # commands/ and agents/ are loaded into agent context. Text that drifts here is # text a judge actually applies, so nothing may follow a LINT id but the id. -git ls-files -z 'plugins/*/commands/*.md' 'plugins/*/agents/*.md' 2>/dev/null | lint_extract | sort -u > "$lint_hits" +git ls-files -z 'plugins/*/commands/*.md' 'plugins/*/agents/*.md' 'plugins/*/skills/plan/*.md' 'plugins/*/skills/plan/phases/*.md' 2>/dev/null | lint_extract | sort -u > "$lint_hits" -for must in plugins/deepgrade/commands/plan.md plugins/deepgrade/agents/plan-auditor.md; do - git ls-files -z 'plugins/*/commands/*.md' 'plugins/*/agents/*.md' 2>/dev/null | tr '\0' '\n' | grep -qxF "$must" \ +for must in plugins/deepgrade/skills/plan/phases/phase-5-audit.md plugins/deepgrade/agents/plan-auditor.md; do + git ls-files -z 'plugins/*/commands/*.md' 'plugins/*/agents/*.md' 'plugins/*/skills/plan/*.md' 'plugins/*/skills/plan/phases/*.md' 2>/dev/null | tr '\0' '\n' | grep -qxF "$must" \ || { fail "PH5-001a: $must is not in the machine-read set — the derivation is wrong, not the repo clean"; lint_bad=1; } done @@ -358,7 +358,7 @@ rm -f "$lint_hits" "$lint_reg" "$lint_hf" "$lint_drift" # PH5-002 / acceptance row A1: rule COUNTS live only in the registry. # # Rule text was not the only thing that drifted. Four different Phase 5 counts were -# in print at once — 14 in plugins/deepgrade/commands/plan.md, 14 and 15 in plugins/deepgrade/agents/plan-auditor.md, +# in print at once — 14 in plugins/deepgrade/skills/plan/phases/phase-5-audit.md, 14 and 15 in plugins/deepgrade/agents/plan-auditor.md, # 16 in the registry, 15 in METHODOLOGY.md — plus a fifth ("13 in Lite mode") in the # same METHODOLOGY sentence. A count is a claim about the rule SET, so it belongs # where the set is defined. @@ -472,7 +472,7 @@ done # =========================================================================== # PH5-010 / acceptance row A3: audit criteria are not in the generator's reach. # -# plugins/deepgrade/commands/plan.md is what the Phase 4 generator reads. It carried a full copy of +# plugins/deepgrade/skills/plan/phases/phase-5-audit.md is what the Phase 4 generator reads. It carried a full copy of # the scoring rubric and the gap matrices — the 1-5 anchors, the Scenario Matrix with # its eight scenarios named, the Cross-Cutting Sweep with its concerns named. A # generator holding that list writes sections matching the list, which is compliance @@ -503,7 +503,7 @@ if printf '%s\n' 'Set iterations = 2 when the loop re-runs.' | grep -qE "$anchor fi # --- generator side: the criteria must be absent ------------------------- -GENERATOR_FILES="plugins/deepgrade/commands/plan.md plugins/deepgrade/commands/quick-plan.md plugins/deepgrade/agents/plan-scaffolder.md" +GENERATOR_FILES="plugins/deepgrade/skills/plan/SKILL.md plugins/deepgrade/skills/plan/phases/*.md plugins/deepgrade/commands/quick-plan.md plugins/deepgrade/agents/plan-scaffolder.md" for gf in $GENERATOR_FILES; do [ -f "$gf" ] || { fail "PH5-010: generator file $gf not found — the subject set is wrong, not the repo clean"; crit_bad=1; continue; } for probe in "$anchor_re:scoring anchor" "$scen_re:Scenario Matrix criteria" "$conc_re:Cross-Cutting criteria"; do @@ -594,7 +594,7 @@ fi # a sentence-initial imperative for the same negation-proofing reason as PH5-011. # =========================================================================== iso_bad=0 -ISO_FILE="plugins/deepgrade/commands/plan.md" +ISO_FILE="plugins/deepgrade/skills/plan/phases/phase-5-audit.md" iso_re='^SPAWN A NEW plan-auditor INSTANCE' if ! printf '%s\n' 'SPAWN A NEW plan-auditor INSTANCE for every audit iteration.' | grep -qE "$iso_re"; then @@ -709,8 +709,8 @@ if ! grep -qxF "$PH5_021_LINE" plugins/deepgrade/agents/plan-auditor.md; then fail "PH5-021: plugins/deepgrade/agents/plan-auditor.md does not require emitting evidence records — the validator has no input, so the gate cannot open" emit_bad=1 fi -if ! grep -qxF "$PH5_022_LINE" plugins/deepgrade/commands/plan.md; then - fail "PH5-022: plugins/deepgrade/commands/plan.md does not require committing the evidence directory — evidence that is not committed cannot be re-checked later" +if ! grep -qxF "$PH5_022_LINE" plugins/deepgrade/skills/plan/phases/phase-5-audit.md; then + fail "PH5-022: plugins/deepgrade/skills/plan/phases/phase-5-audit.md does not require committing the evidence directory — evidence that is not committed cannot be re-checked later" emit_bad=1 fi @@ -733,10 +733,10 @@ fi # =========================================================================== gate_bad=0 GATE_LINE='PASS = CANARY_OK AND EVIDENCE_OK AND VERIFIED AND INFRA_OK' -gate_block=$(sed -n '/^$/,/^<\/gate_expression>$/p' plugins/deepgrade/commands/plan.md 2>/dev/null) +gate_block=$(sed -n '/^$/,/^<\/gate_expression>$/p' plugins/deepgrade/skills/plan/phases/phase-5-audit.md 2>/dev/null) if [ -z "$gate_block" ]; then - fail "PH5-041: plugins/deepgrade/commands/plan.md has no delimited block" + fail "PH5-041: plugins/deepgrade/skills/plan/phases/phase-5-audit.md has no delimited block" gate_bad=1 else printf '%s\n' "$gate_block" | grep -qxF "$GATE_LINE" \ @@ -753,10 +753,10 @@ else fi # The superseded form must be gone, not merely superseded by a newer block below it. -if grep -qE '^IF score (>=|<) [0-9]+' plugins/deepgrade/commands/plan.md; then +if grep -qE '^IF score (>=|<) [0-9]+' plugins/deepgrade/skills/plan/phases/phase-5-audit.md; then gate_bad=1 - fail "PH5-041: the score-based gate branch is still present in plugins/deepgrade/commands/plan.md" - grep -nE '^IF score (>=|<) [0-9]+' plugins/deepgrade/commands/plan.md | sed 's/^/ /' | head -4 + fail "PH5-041: the score-based gate branch is still present in plugins/deepgrade/skills/plan/phases/phase-5-audit.md" + grep -nE '^IF score (>=|<) [0-9]+' plugins/deepgrade/skills/plan/phases/phase-5-audit.md | sed 's/^/ /' | head -4 fi [ "$gate_bad" -eq 0 ] && pass "PH5-041: the gate keys on canary, evidence, verdicts and infra — not on a score" @@ -770,7 +770,7 @@ fi # UNMET: Phase 2 migration has no rollback step" names a defect it can actually fix. # =========================================================================== fb_bad=0 -fb_block=$(sed -n '/^$/,/^<\/revision_feedback>$/p' plugins/deepgrade/commands/plan.md 2>/dev/null) +fb_block=$(sed -n '/^$/,/^<\/revision_feedback>$/p' plugins/deepgrade/skills/plan/phases/phase-5-audit.md 2>/dev/null) fb_forbidden='dimension|score|/40|points|threshold|GREEN|YELLOW|ORANGE' if ! printf '%s\n' 'Dimension 4 scored 2 — improve rollback coverage.' | grep -qEi "$fb_forbidden"; then @@ -783,7 +783,7 @@ if printf '%s\n' 'LINT-03 UNMET: Phase 2 migration has no rollback step. Locatio fi if [ -z "$fb_block" ]; then - fail "PH5-040: plugins/deepgrade/commands/plan.md has no delimited block defining what goes back to the generator" + fail "PH5-040: plugins/deepgrade/skills/plan/phases/phase-5-audit.md has no delimited block defining what goes back to the generator" fb_bad=1 else offend=$(printf '%s\n' "$fb_block" | grep -nEi "$fb_forbidden" || true) @@ -810,9 +810,9 @@ fi # mentions the word "waiver" — a mention survives the rule being deleted. # =========================================================================== wv_bad=0 -wv_block=$(sed -n '/^$/,/^<\/waiver_condition>$/p' plugins/deepgrade/commands/plan.md 2>/dev/null) +wv_block=$(sed -n '/^$/,/^<\/waiver_condition>$/p' plugins/deepgrade/skills/plan/phases/phase-5-audit.md 2>/dev/null) if [ -z "$wv_block" ]; then - fail "PH5-060: plugins/deepgrade/commands/plan.md has no delimited block" + fail "PH5-060: plugins/deepgrade/skills/plan/phases/phase-5-audit.md has no delimited block" wv_bad=1 else for term in 'infra_gaps == 0' 'score >= 35' 'canary_found == true'; do @@ -832,8 +832,8 @@ fi # =========================================================================== hol_bad=0 HOL_LINE='RUN one additional judge with no rubric, no criterion list, and no dimension names.' -grep -qxF "$HOL_LINE" plugins/deepgrade/commands/plan.md \ - || { fail "PH5-050: plugins/deepgrade/commands/plan.md does not run a rubric-free pass — nothing checks the criteria for completeness"; hol_bad=1; } +grep -qxF "$HOL_LINE" plugins/deepgrade/skills/plan/phases/phase-5-audit.md \ + || { fail "PH5-050: plugins/deepgrade/skills/plan/phases/phase-5-audit.md does not run a rubric-free pass — nothing checks the criteria for completeness"; hol_bad=1; } [ -f plugins/deepgrade/docs/planning-techniques/lint-candidates.md ] \ || { fail "PH5-050: plugins/deepgrade/docs/planning-techniques/lint-candidates.md missing — unmapped findings have nowhere to land"; hol_bad=1; } [ "$hol_bad" -eq 0 ] && pass "PH5-050: a rubric-free pass runs and its unmapped findings land in lint-candidates.md" @@ -846,9 +846,9 @@ grep -qxF "$HOL_LINE" plugins/deepgrade/commands/plan.md \ # signature of threshold-aiming. Keeping the series costs nothing and is the only # way to see that pattern at all. # =========================================================================== -grep -qF 'score_history' plugins/deepgrade/commands/plan.md \ +grep -qF 'score_history' plugins/deepgrade/skills/plan/phases/phase-5-audit.md \ && pass "PH5-051: audit scores are retained as a series for distribution monitoring" \ - || fail "PH5-051: plugins/deepgrade/commands/plan.md does not record score_history — threshold-aiming would be invisible" + || fail "PH5-051: plugins/deepgrade/skills/plan/phases/phase-5-audit.md does not record score_history — threshold-aiming would be invisible" # =========================================================================== # 16R. Root-doc conformance (§9.2, class G) — the root-level docs.