# Requirements: QSP-44444 — Smooth Agentic Development Flow

## Status
📋 Draft — awaiting approval

---

## Summary

The current agent system has underdefined workflow mechanics: agents don't always know when Agent Smith runs relative to validation, when to self-heal vs. pause and ask, or that unit and component testing can happen in parallel. This ticket replaces the ASCII development loop in `AGENTS.md` with a Mermaid diagram, introduces a new `base/workflow.md` as the canonical per-phase operational reference, splits Agent Smith into a FAST structural check (auto-triggered post-coding) and a FULL semantic check (post-human-verify), adds a "Pause and Ask" mode for ambiguous errors, and declares explicit parallel execution points for the test-writing phase.

---

## Workflow Diagram (Target State)

```mermaid
flowchart TD
    REFINE["🔍 Phase 1: Refinement\nrequirements.agent"] --> RG{"Human approves\nrequirements.md?"}
    RG -->|"No — iterate"| REFINE
    RG -->|"Yes"| CODE["⚙️ Phase 2a: Coding\ncoding.agent"]
    CODE --> VAL{"typecheck + lint"}
    VAL -->|"Ambiguous error"| PAUSE["⏸ Pause & Ask\nhuman for direction"]
    PAUSE --> CODE
    VAL -->|"Fail ≤3×, retry"| CODE
    VAL -->|"Fail, retries exhausted"| ESC["⚠️ Escalate to human"]
    VAL -->|"Pass"| FAST["🔬 Agent Smith FAST\n6 structural checks\nauto-triggered"]
    FAST -->|"BLOCK, fix loop ≤3×"| CODE
    FAST -->|"BLOCK, loop exhausted"| ESC
    FAST -->|"PASS"| HV["👁️ Human Verify\nin browser"]
    HV -->|"Needs revision"| CODE
    HV -->|"Approved"| FULL["🔬 Agent Smith FULL\nall 17 checks"]
    FULL -->|"BLOCK, fix loop ≤3×"| CODE
    FULL -->|"BLOCK, loop exhausted"| ESC
    FULL -->|"PASS"| PAR["🧪 Phase 3: Tests\nparallel trigger"]
    PAR --> UT["unit-testing-agent"]
    PAR --> CT["component-testing-agent"]
    UT --> EXEC["test-execution-agent"]
    CT --> EXEC
    EXEC -->|"Same error ×2"| PAUSE
    EXEC -->|"Fail ≤5×, fix"| CODE
    EXEC -->|"All pass + coverage ≥90%"| DONE["✅ Complete → Review"]
```

---

## Acceptance Criteria

- [ ] AC-1: A new `base/workflow.md` file exists containing: the canonical Mermaid flowchart, per-agent gate conditions, loop limits, parallel execution points, pause-and-ask trigger criteria, and escalation format.
- [ ] AC-2: `AGENTS.md` development loop section is replaced with a Mermaid diagram (rendered on GitHub) that shows the full loop including Smith FAST, Smith FULL, parallel test phases, and pause-and-ask.
- [ ] AC-3: `agent-smith.agent.md` defines two explicit invocation modes — `FAST` (6 structural checks, auto-triggered) and `FULL` (all 17 checks, post-human-verify). Each mode lists exactly which checks it runs.
- [ ] AC-4: `coding.agent.md` Phase 1 triggers Agent Smith FAST automatically after typecheck + lint pass. Only after FAST PASS does the coding agent present the summary to the human.
- [ ] AC-5: `error-recovery.skill.md` defines a "Pause and Ask" path — distinct from the 3-retry escalation — with 4 explicit ambiguity criteria and a standard pause message template.
- [ ] AC-6: `unit-testing.agent.md` and `component-testing.agent.md` each declare that they can be triggered in parallel (by the orchestrator) and that the fixing loop is always sequential.
- [ ] AC-7: `implementation.prompt.md` has 7 explicit phases (Code → Human Verify → Smith FULL → Tests → Execution Report → Final Human Check → Summary). Phase 6 gate requires explicit human approval. Phase 7 creates/updates `summary.md` with description, "What Changed" bullets, and ACs verified.
- [ ] AC-8: Phase 2 (Human Verify) in `implementation.prompt.md` includes a specific 4-item browser checklist: (1) feature renders, (2) loading/error/empty states, (3) navigation, (4) no console errors.
- [ ] AC-9: All modified files are self-consistent — no instruction in one file contradicts another.
- [ ] AC-10: All 6 review agents (`code-review`, `security-review`, `architect`, `accessibility`, `ux-review`, `documentation`) have a "Workflow Position" section referencing `base/workflow.md`, declaring their phase, their inputs, and the fix-loop behaviour on 🔴 findings.
- [ ] AC-11: `.github/scripts/refresh-codebase-knowledge.mjs` exists and, when run via `npm run knowledge:refresh`, scans `src/app/models/`, `src/app/utils/`, `src/app/api/`, and `src/app/pages/`, reports exports changed since the "Last verified" date, and updates that date in `codebase.md`.
- [ ] AC-12: `.github/prompts/distill-findings.prompt.md` exists and defines a periodic self-improvement workflow: read all `findings/*.md`, identify patterns appearing 3+ times, propose targeted updates to `base/` rules or agent files, require human approval before any change is applied.
- [ ] AC-13: `refinement.agent.md` is deleted. `requirements.agent.md` absorbs its ad-hoc mode (no context.md required — output defaults to `.github/tickets/ad-hoc-<slug>/requirements.md`).
- [ ] AC-14: `integration.agent.md` is deleted. Its phase transition logic and escalation format are merged into `full-cycle.prompt.md`.
- [ ] AC-15: `documentation.agent.md` is deleted. A "Documentation Review" section is added to `code-review.agent.md` covering stale refs, JSDoc, and TODOs. `documentation-sync.prompt.md` is deleted.
- [ ] AC-16: `test-execution.agent.md` is deleted. `test-execution.skill.md` is created and referenced by `unit-testing.agent.md`, `component-testing.agent.md`, and `implementation.prompt.md`.
- [ ] AC-17: `findings-persistence.skill.md` is deleted. Agent files already contain identical content; the skill is redundant.
- [ ] AC-18: `software-principles.skill.md` is deleted. Content is moved to `base/knowledge/software-principles.md`. `copilot-instructions.md` pointer is updated.
- [ ] AC-19: `hallucination-detection.skill.md` is renamed to `agent-smith-checks.skill.md`. All references updated.
- [ ] AC-20: `agent-smith.prompt.md` is deleted. `pre-commit-check.prompt.md` is created — runs Smith FAST on specified files as a lightweight pre-commit gate.
- [ ] AC-21: `refinement.prompt.md` is deleted. `problem-refinement.prompt.md` gains an ad-hoc mode note (no ticket ID required).
- [ ] AC-22: `write-a11y-tests.prompt.md` is deleted. `write-component-tests.prompt.md` gains an `--a11y` mode flag.
- [ ] AC-23: `pattern-matching.skill.md` lookup table is removed. The table moves to `base/knowledge/codebase.md` under "Pattern Examples". The skill retains only the 5-step procedure.
- [ ] AC-24: `changelist.skill.md` is created, defining when to use multi-CL mode (≥5 files or ≥3 distinct layers), compile-clean CL boundaries, per-CL gates (typecheck + lint + Smith FAST only — **no human micro-review**; human reviews the complete feature once after all CLs), naming convention, and documentation format in `implementation-plan.md`.
- [ ] AC-25: `coding.agent.md` and `implementation.prompt.md` declare multi-CL mode: when triggered, Phase 3 runs one CL at a time with per-CL gates; full tests run only after all CLs complete.
- [ ] AC-26: Phase 8 (Self-Learning) is added to `implementation.prompt.md` as a **conditional** step: only agents whose loop count exceeded 1 or that triggered a pause-and-ask write a structured lessons block (`Problem / Cause / Fix / Prevention`). Agents with smooth execution write nothing. No base files are modified automatically.
- [ ] AC-27: `base/workflow.md` includes the conditional lessons block format and the two-tier self-learning model (Tier 1 per-feature conditional, Tier 2 periodic human-gated via `distill-findings.prompt.md`).
- [ ] AC-28: `AGENTS.md` counts and catalogue updated to reflect final artefact counts: 14 agents, 12 skills (incl. test-execution, changelist, system-refinement), 13 prompts, 7 knowledge files.
- [ ] AC-29: `base/knowledge/testing-patterns.md` (single file) is created, containing all verbose CT and E2E boilerplate extracted from `component-testing.agent.md` and `e2e-testing.agent.md`. File has two clearly labelled sections: `## Component Testing Patterns` and `## E2E Testing Patterns`.
- [ ] AC-30: `coding.agent.md` is ≤200 lines. "Code Generation Rules" replaced with pointer blocks to `copilot-instructions.md` (placement, TypeScript, component, utils rules) and `base/knowledge/codebase.md` (canonical patterns). Phase 1 step 2 gains an explicit "check codebase.md Domain Types and Existing Utils before creating any new interface or utility" mandate. Error Handling Patterns code block and Validation Checklist remain in the agent.
- [ ] AC-31: `base/knowledge/codebase.md` gains a "Canonical Patterns" section with the 7 code examples extracted from `coding.agent.md` (DataTable, tile hierarchy, API layer, backend function, record mapping, DQL lookup, URL params) plus a "Testing Utilities" sub-section with CT test structure, Grail mock util table, and Page Object scaffold.
- [ ] AC-32: `component-testing.agent.md` is ≤250 lines. All verbose boilerplate moved to `base/knowledge/testing-patterns.md` § Component Testing Patterns. Agent retains: directory structure table, compressed `test.use` field list, compressed workflow steps, Parallel Execution declaration, key ❌/✅ rules, pointer to the knowledge file.
- [ ] AC-33: `e2e-testing.agent.md` is ≤250 lines. All verbose boilerplate moved to `base/knowledge/testing-patterns.md` § E2E Testing Patterns. Agent retains: Key Differences table, directory structure table, import boundary rules, compressed workflow steps, Parallel Execution declaration, pointer to the knowledge file.
- [ ] AC-34: All remaining ✅ Keep agents pass a signal-density check: no narrative paragraphs without an action, no content duplicated from `copilot-instructions.md`, Findings Persistence sections compressed to ≤5 lines. `unit-testing.agent.md` ≤280 lines; `requirements.agent.md` ≤320 lines; all others ≤220 lines.
- [ ] AC-35: `system-refinement.skill.md` exists, contains: change classification table (🔴/🟡/🟢), 5-check overengineering gate, evaluation procedure (7 steps), proposal template, and anti-patterns list. File is ≤120 lines.
- [ ] AC-36: `refine-system.prompt.md` exists, defines three modes (targeted, pain-point, health-check), invokes `system-refinement.skill.md`, has an explicit overengineering indicator that fires when 🟢 additions outnumber 🔴 removals, and never applies changes without explicit human approval.

---

## Key Decisions

| # | Decision | Rationale |
|---|---|---|
| D-1 | Create `base/workflow.md` as the single source of truth for workflow mechanics | A single canonical document prevents drift between AGENTS.md, skills, and agent files — all other files point to it rather than duplicating rules |
| D-2 | Mermaid diagram in `AGENTS.md` (not ASCII) | Mermaid renders on GitHub; the diagram is the first thing contributors see — it must be readable without scrolling through code blocks |
| D-3 | Review agents updated to 7-phase flow within this ticket | Gap analysis shows review agents score 4/10 on workflow integration; updating 6 markdown files is low-effort and high-value; no external systems required |
| D-4 | Agent Smith FAST runs automatically after typecheck+lint pass, before human verify | Humans should never be asked to verify obviously broken output (empty stubs, wrong imports, missing consumers); fast structural checks are low-cost |
| D-5 | Agent Smith FAST = 6 structural checks (post-coding); FULL = all 17 checks (post-tests-passing) | Structural checks don't require reading ACs and run quickly; FULL needs test files to exist so it can review them too |
| D-6 | "Pause and Ask" is a separate path from escalation | Escalation fires after retries are exhausted; pause-and-ask fires immediately when the error is genuinely ambiguous — no retries on unknowable problems |
| D-7 | Loop limits unchanged: Smith FAST ×3, Smith FULL ×3, test fix ×5, coding retry ×3 | These limits were calibrated from observation and remain correct; refining them is out of scope |
| D-8 | Phase 2 plan review conditional on context.md existing | Ticket-based work warrants a redirect checkpoint; ad-hoc prompts benefit from speed over ceremony |
| D-9 | Phase 6 last human check always mandatory | Human is the final quality gate; automated fix loops can silently change what was approved in Phase 4 |
| D-10 | Phase 7 summary always present, always agent-written | Derived mechanically from files touched and requirements.md ACs — no human input needed |
| D-11 | `codebase.md` refresh script created as local Node.js tool | Agents currently note "codebase.md is stale" but have no automated way to refresh it; a local script with no external dependencies closes this gap |
| D-12 | Refresh script updates "Last verified" date and reports changed exports; does not overwrite narrative sections | Full regeneration risks losing curated context; a targeted "what changed" report + updated date is safer and sufficient |
| D-14 | Findings distillation prompt created for periodic self-improvement | Without CI feedback, distillation is the only way to turn accumulated findings into improved base rules; runs periodically on human request |
| D-15 | `refinement.agent.md` (507 lines) merged into `requirements.agent.md` | Identical purpose — only difference is output path; that's a config flag, not a separate 507-line agent |
| D-16 | `integration.agent.md` merged into `full-cycle.prompt.md` | Pure delegator with no domain knowledge; its phase table is already duplicated in AGENTS.md and full-cycle |
| D-17 | `documentation.agent.md` merged into `code-review.agent.md` | Documentation review (stale refs, JSDoc) is a natural subset of code review; separate agent adds overhead for low unique value |
| D-18 | `test-execution.agent.md` converted to `test-execution.skill.md` | No domain knowledge — just runs npm commands; a shared skill is DRY-er and reduces maintenance surface |
| D-19 | `findings-persistence.skill.md` removed | Every agent already contains identical content; the skill adds indirection with zero new information |
| D-20 | `software-principles.skill.md` converted to `base/knowledge/software-principles.md` | Declarative content (what KISS/YAGNI mean) belongs in knowledge files, not skills; skills are procedures |
| D-21 | `hallucination-detection.skill.md` renamed to `agent-smith-checks.skill.md` | Used exclusively by Agent Smith; "skill" implies multi-agent composability that doesn't exist here |
| D-22 | Multi-CL mode added: ≥5 files or ≥3 distinct layers triggers changelist planning | Google DORA (2023): PRs <200 lines get 3× more meaningful review per line; per-CL gates are typecheck+lint+Smith FAST only; full tests only after final CL |
| D-23 | Phase 8 (self-learning) added: structured lessons block per-feature, no auto-modification of base files | Two-tier model per Microsoft AutoGen / Constitutional AI research: Tier 1 (automatic observations) never touches base files; Tier 2 (periodic distillation) is human-gated |
| D-24 | Canonical code patterns extracted from `coding.agent.md` → `codebase.md` "Canonical Patterns" section | Patterns are reference data (what things look like), not agent procedures (what to do). Reference data belongs in the knowledge layer; agent files contain procedure + pointer. Same separation as domain types → `codebase.md`. |
| D-25 | `component-testing.agent.md` and `e2e-testing.agent.md` tutorial content extracted to dedicated knowledge files | Agent files are procedure specs, not tutorials. Tutorials answer "what does it look like?" — knowledge files. Agents answer "what do I do, in what order, with what gate?" — agent files. Mixing both inflates agent files 3-4× past target and buries critical procedure under boilerplate. |
| D-26 | Signal-density rule applied to all ✅ Keep agents in a dedicated overhaul pass | Every line must be a procedure, decision rule, ❌/✅ example, or pointer. Background narrative, restatements of `copilot-instructions.md`, and Findings Persistence verbosity add noise without adding instruction. Compressed agents are followed more reliably (instruction-dilution finding from Claude long-context research). |
| D-27 | `findings/metrics.md` removed from scope | **🔴 Overengineering**: 3 agents maintaining a separate log in a consistent format duplicates what `findings/*.md` already captures. The only consumer is `distill-findings.prompt.md`, which reads `findings/*.md` directly. Adding cross-agent maintenance overhead for zero new information violates DRY and YAGNI. |
| D-28 | Phase 8 lessons blocks conditional, not mandatory | **🔴 Overengineering**: mandating every agent write lessons on every feature means 5-7 empty blocks per smooth feature. Lessons only have value when something went wrong (loop count > 1 or escalation). Conditional trigger reduces noise and preserves the signal. |
| D-29 | CT and E2E knowledge files merged into single `testing-patterns.md` | **🟡 Simplification**: two separate 200-line files with a 5-file knowledge directory is unnecessary fragmentation. One file with two sections (CT / E2E) reduces the number of files agents must enumerate. Both are read together anyway (CT agent and E2E agent are triggered in the same phase). |
| D-30 | changelist.skill.md per-CL gate removes human micro-review | **🔴 Overengineering**: human micro-review per CL for a 10-CL feature means 10 interruptions vs the original 1. This defeats the purpose of splitting into CLs. Per-CL gate is typecheck+lint+Smith FAST only; human review happens once for the complete feature. |
| D-31 | `coding.agent.md` gains explicit "check codebase.md before creating" mandate | **Quality improvement for code generation**: agents frequently create duplicate interfaces and utils that already exist. An explicit check-first step in Phase 1 addresses the most common cause of scope creep and dead code in generated output. |
| D-32 | `system-refinement.skill.md` + `refine-system.prompt.md` added to scope | Fills a real gap: no structured procedure for improving the agent system itself. The overengineering gate built into the skill ensures the system self-improvement process cannot itself become overengineered. |

---

## Data Model

N/A — this ticket modifies agent workflow documentation and skill files, not application data.

---

## UX / UI Specification

N/A — output is agent documentation, not UI.

---

## API Contracts

N/A.

---

## DQL Queries

N/A.

---

## Implementation Plan

### Consumer Impact Analysis

> **Signal-density rule for all steps**: every line written must be a procedure, decision rule, ❌/✅ example, or pointer. No narrative paragraphs. No redundancy with other files. Targets: skills 50–120 lines, agents 100–250 lines, prompts 40–80 lines. Knowledge files have no limit.

| File | Required change |
|---|---|
| `AGENTS.md` | Replace ASCII development loop with Mermaid diagram; update gate table for all phases |
| `.github/base/workflow.md` | New canonical workflow reference |
| `.github/agents/agent-smith.agent.md` | Add FAST/FULL invocation modes; update FULL trigger to post-tests |
| `.github/agents/coding.agent.md` | Phase 2 conditional plan review; step 3.5 Smith FAST; updated Phase 1 gate; **add "check codebase.md before creating new types/utils" to Phase 1 step 2** |
| `.github/agents/requirements.agent.md` | Phase 7 always-present agent-written summary; **add "self-challenge draft" step before finalising** |
| `.github/skills/error-recovery.skill.md` | Pause-and-ask path + template |
| `.github/prompts/implementation.prompt.md` | **Step 7**: Full 7-phase restructure (Phases 1–7); Phase 6 final human check; Phase 7 agent-written summary; 4-item browser-verify checklist. **Steps 22+23**: multi-CL loop + conditional Phase 8 append to this structure. |
| `.github/agents/code-review.agent.md` | Add Workflow Position section |
| `.github/agents/security-review.agent.md` | Add Workflow Position section |
| `.github/agents/architect.agent.md` | Add Workflow Position section |
| `.github/agents/accessibility.agent.md` | Add Workflow Position section |
| `.github/agents/ux-review.agent.md` | Add Workflow Position section |
| `.github/agents/documentation.agent.md` | Add Workflow Position section |
| `.github/scripts/refresh-codebase-knowledge.mjs` | New script — codebase knowledge refresh |
| `package.json` | Add `knowledge:refresh` script |
| `.github/prompts/distill-findings.prompt.md` | New self-improvement prompt (reads `findings/*.md` directly — no separate metrics file) |
| `.github/agents/coding.agent.md` | **Overhaul**: Code Generation Rules stripped, canonical patterns moved to `codebase.md`, duplicate rules replaced with pointers, "check before create" mandate added. Target ≤200 lines. *(cumulative with Step 4 changes)* |
| `.github/agents/component-testing.agent.md` | **Overhaul**: Verbose boilerplate moved to `testing-patterns.md`, agent rewritten to procedure-only format. Target ≤250 lines. *(cumulative with Step 6 changes)* |
| `.github/agents/e2e-testing.agent.md` | **Overhaul**: `data-testid` reference, full PO/Assertion templates, complete test examples moved to `testing-patterns.md`, agent rewritten. Target ≤250 lines. |
| `.github/base/knowledge/codebase.md` | Add "Canonical Patterns" section (7 code examples + testing utilities). *(cumulative with Step 19 changes)* |
| `.github/base/knowledge/testing-patterns.md` | New file — CT and E2E boilerplate in two sections |
| `.github/agents/unit-testing.agent.md` | AI-consumability pass. Target ≤280 lines. *(cumulative with Step 6 changes)* |
| `.github/agents/requirements.agent.md` | AI-consumability pass. Target ≤320 lines. *(cumulative with Step 12 changes)* |
| `.github/agents/security-review.agent.md` | AI-consumability pass: compress Findings Persistence, remove narrative, verify within target. |
| `.github/agents/architect.agent.md` | AI-consumability pass: compress Findings Persistence, remove narrative, verify within target. |
| `.github/agents/accessibility.agent.md` | AI-consumability pass: compress Findings Persistence, remove narrative, verify within target. |
| `.github/agents/ux-review.agent.md` | AI-consumability pass: compress Findings Persistence, remove narrative, verify within target. |
| `.github/agents/dql-query.agent.md` | AI-consumability pass: compress Findings Persistence, remove narrative, verify within target. |
| `.github/skills/system-refinement.skill.md` | New skill — structured agent system improvement with overengineering gate |
| `.github/prompts/refine-system.prompt.md` | New prompt — entry point for system refinement (targeted / pain-point / health-check modes) |

---

### Step 1: CREATE `.github/base/workflow.md`

- **File**: `.github/base/workflow.md`
- **Changes**: New canonical workflow reference containing:
  1. Mermaid source (authoritative copy — AGENTS.md references it)
  2. Per-phase table: phase name, trigger, responsible agent, gate condition, max loops
  3. Parallel execution points table
  4. Pause-and-ask trigger criteria (4 conditions) + message template
  5. Escalation format
  6. Loop limit summary table
- **Verification**: File exists, all sections present, Mermaid syntax is valid

---

### Step 2: MODIFY `AGENTS.md`

- **File**: `AGENTS.md`
- **Changes**:
  1. Replace the ASCII art block in "Development Loop" section with the Mermaid diagram
  2. Update the gate table — add two new rows for Smith FAST and Smith FULL
  3. Add pointer: `> Full per-phase operational reference: [.github/base/workflow.md](.github/base/workflow.md)`
- **Verification**: Mermaid block present; gate table has Smith FAST + FULL rows; pointer line present

---

### Step 3: MODIFY `.github/agents/agent-smith.agent.md`

- **File**: `.github/agents/agent-smith.agent.md`
- **Changes**:
  1. Add **Invocation Modes** section (after Skills table) defining FAST and FULL modes with their respective check lists
  2. Update step 5 in "How to work" to apply only the mode-specific check list
  3. Update step 1 in Session Start Protocol to extract the invocation mode from context
- **Verification**: Both mode sections present; FAST lists 6 checks; FULL lists all 17; FAST is a strict subset of FULL

---

### Step 4: MODIFY `.github/agents/coding.agent.md`

- **File**: `.github/agents/coding.agent.md`
- **Changes** in Phase 1 section:
  1. After step 3 (validate typecheck + lint), insert new step 3.5: invoke Agent Smith FAST, fix on BLOCK (max 3 loops), escalate after 3
  2. Update Phase 1 gate to: `typecheck exits 0 AND lint exits 0 AND Agent Smith FAST PASS`
- **Verification**: Phase 1 gate includes Smith FAST; "present to human" step follows Smith FAST PASS

---

### Step 5: MODIFY `.github/skills/error-recovery.skill.md`

- **File**: `.github/skills/error-recovery.skill.md`
- **Changes**:
  1. Add "Ambiguous Error" branch at the TOP of the decision tree (before any retry checks) with 4 trigger conditions
  2. Add "Pause and Ask" message template (named format block)
  3. Add **Pause** row to Recovery Levels table: trigger = any ambiguity condition; action = present options; max retries = 0
- **Verification**: Ambiguous branch is first in the tree; template has all required fields; Recovery Levels table has 4 rows (Pause, Self-heal, Adapt, Escalate)

---

### Step 6: MODIFY `.github/agents/unit-testing.agent.md` and `component-testing.agent.md`

- **Files**: both agent files
- **Changes**: Add a **Parallel Execution** section near the top of each file stating:
  - Both agents can be triggered simultaneously by the orchestrator
  - Test writing is parallel; production code fixing is always sequential
- **Verification**: Both files have the section; wording is consistent

---

### Step 7: RESTRUCTURE `implementation.prompt.md` — full phase model with Phases 6 and 7

- **File**: `implementation.prompt.md`
- **Changes**: Restructure the prompt to match the Mermaid diagram in `base/workflow.md`:
  1. **Phase 1 — Code**: ends when typecheck + lint + Smith FAST all pass (Smith FAST replaces the current mid-Phase 1.5 position — after QSP-44444 Step 4, Smith FAST is already in the coding agent, so Phase 1 gate is `typecheck+lint+Smith FAST PASS`)
  2. **Phase 2 — Human Verify**: present implementation summary; ask human to verify in browser with the specific checklist: "(1) main feature renders correctly, (2) loading/error/empty states behave as expected, (3) navigation to/from the feature works, (4) no console errors visible". Gate: human explicit approval.
  3. **Phase 3 — Agent Smith FULL**: runs all 17 checks post-human-verify. Gate: PASS verdict. Max 3 loops.
  4. **Phase 4 — Tests** (parallel): unit-testing-agent + component-testing-agent triggered simultaneously. Gate: all tests pass, coverage ≥90%. Max 5 fix loops.
  5. **Phase 5 — Test Execution Report**: test-execution-skill summarises pass/fail counts and coverage per file. If Phase 8 (conditional) applies: agents that had loop count > 1 write lessons blocks.
  6. **Phase 6 — Final Human Check** (D-9): present: files changed, ACs verified, outstanding 🟡/🔵 findings from Agent Smith. Ask: "Does this look correct before handoff to review?" Gate: explicit human yes. *This is the last opportunity to revert any Phase 4 fix that changed approved behaviour.*
  7. **Phase 7 — Agent-Written Summary** (D-10): create/update `.github/tickets/<TICKET_ID>/summary.md` with: one-paragraph description, "What Changed" bullets derived from files touched, ACs verified. Append phase log to `implementation-plan.md`. Update `cache.md` with COMPLETE status.
- **Note**: Steps 22 (multi-CL mode inside Phase 4) and 23 (conditional Phase 8 inside Phase 5) add to this structure — apply after this step.
- **Verification**: All 7 phases present in the prompt; Phase 6 gate requires explicit human "yes"; Phase 7 creates/updates `summary.md`; Phase 2 browser-verify checklist has all 4 items

---

### Step 8: MODIFY 6 review agent files

- **Files**: `code-review.agent.md`, `security-review.agent.md`, `architect.agent.md`, `accessibility.agent.md`, `ux-review.agent.md`, `documentation.agent.md`
- **Changes**: Add a **Workflow Position** section to each file (near the top, after the Skills table):
  ```markdown
  ## Workflow Position

  This agent runs in the **Review phase** — after Phase 7 (summary), before ticket closure.

  **Inputs**: all production files from Phase 3 (coding) + all test files from Phase 5.
  **On 🔴 findings**: the orchestrator routes back to coding.agent (Phase 3). Max 3 fix loops, then escalate.
  **On zero 🔴 findings**: declare clean — ticket advances to closure.

  See `.github/base/workflow.md` for the full 7-phase operational reference.
  ```
- **Verification**: All 6 files have the Workflow Position section; wording references `workflow.md`

---

### Step 9: CREATE `.github/scripts/refresh-codebase-knowledge.mjs` and add npm script

- **Files**: `.github/scripts/refresh-codebase-knowledge.mjs`, `package.json`
- **Changes**:
  1. Script reads the "Last verified" date from `base/knowledge/codebase.md`
  2. Scans `src/app/models/`, `src/app/utils/`, `src/app/api/`, `src/app/pages/` for `.ts`/`.tsx` files modified after that date
  3. For each changed file, extracts exported symbol names (interfaces, types, functions) using regex on `export` keywords
  4. Prints a structured "Changed since last verification" report to stdout
  5. Updates the "Last verified" date in `codebase.md` to today
  6. Exits with code 1 if stale files were found (so agents can detect it), code 0 if up to date
  7. Add to `package.json`: `"knowledge:refresh": "node .github/scripts/refresh-codebase-knowledge.mjs"`
- **Verification**: `npm run knowledge:refresh` runs without error; prints a change report when files are modified; updates "Last verified" in `codebase.md`

---

### Step 11: CREATE `.github/prompts/distill-findings.prompt.md`

- **File**: `.github/prompts/distill-findings.prompt.md`
- **Changes**: New periodic self-improvement prompt:
  1. Read all `findings/*.md` files (no separate metrics log needed — findings files contain all signal)
  2. Identify patterns appearing **3+ times** across tickets (same error type, same anti-pattern, same Smith check firing repeatedly)
  3. For each pattern: propose a targeted update to `base/instructions.md`, an agent file, a skill file, or a knowledge file that would prevent the pattern from recurring
  4. Present proposals to human for approval — never apply automatically
  5. Gate: human explicit approval of each proposed change
- **Verification**: File exists; procedure has all 5 steps; no metrics.md reference; gate condition is explicit

---

### Step 12: MERGE `refinement.agent.md` → `requirements.agent.md`; DELETE `refinement.agent.md` and `refinement.prompt.md`

- **Files**: `requirements.agent.md` (modify), `refinement.agent.md` (delete), `refinement.prompt.md` (delete), `problem-refinement.prompt.md` (modify)
- **Changes**:
  1. Add ad-hoc mode to `requirements.agent.md`: if no `<TICKET_ID>` is provided, derive a slug from the topic, create `.github/tickets/ad-hoc-<slug>/`, output `requirements.md` there
  2. After Step 9 ("Draft specification"), insert new **Step 9.5 — Self-challenge**: before presenting the draft to the human, the agent reviews its own draft against each AC and each step in the implementation plan: "Does each step describe HOW the AC is satisfied? Is there any step with an unverified technical assumption?" Flag gaps and fill them before presenting.
  3. Add a one-line note to `problem-refinement.prompt.md`: "No ticket ID? Provide a topic instead — the agent will create an ad-hoc folder automatically."
  4. Delete `refinement.agent.md` and `refinement.prompt.md`
- **Verification**: `requirements.agent.md` handles both ticket and ad-hoc modes; self-challenge step present before "present to human"; `refinement.agent.md` no longer exists

---

### Step 13: MERGE `integration.agent.md` → `full-cycle.prompt.md`; DELETE `integration.agent.md`

- **Files**: `full-cycle.prompt.md` (modify), `integration.agent.md` (delete)
- **Changes**: Move the Phase Transition Table and Escalation format from `integration.agent.md` into `full-cycle.prompt.md`. Delete `integration.agent.md`.
- **Verification**: `full-cycle.prompt.md` contains the full phase transition table; `integration.agent.md` no longer exists

---

### Step 14: MERGE `documentation.agent.md` → `code-review.agent.md`; DELETE `documentation.agent.md` and `documentation-sync.prompt.md`

- **Files**: `code-review.agent.md` (modify), `documentation.agent.md` (delete), `documentation-sync.prompt.md` (delete)
- **Changes**: Add a "Documentation Review" section to `code-review.agent.md` (stale refs, JSDoc gaps, TODO comments). Update `review.prompt.md` to remove the separate documentation agent invocation.
- **Verification**: `code-review.agent.md` has Documentation Review section; deleted files no longer exist

---

### Step 15: CONVERT `test-execution.agent.md` → `test-execution.skill.md`; DELETE agent

- **Files**: `test-execution.skill.md` (create), `test-execution.agent.md` (delete), `unit-testing.agent.md` (modify), `component-testing.agent.md` (modify), `implementation.prompt.md` (update reference)
- **Changes**: Extract the command-running and report-formatting logic into a skill. Each testing agent composes the skill. Delete the agent file.
- **Verification**: `test-execution.skill.md` exists; `test-execution.agent.md` no longer exists; both testing agents reference the skill

---

### Step 16: DELETE `findings-persistence.skill.md`

- **File**: `findings-persistence.skill.md` (delete)
- **Changes**: Remove the file. No agent references change — each agent already has its own findings persistence section. Update `AGENTS.md` skills catalogue.
- **Verification**: File no longer exists; no agent imports it

---

### Step 17: CONVERT `software-principles.skill.md` → `base/knowledge/software-principles.md`; DELETE skill

- **Files**: `base/knowledge/software-principles.md` (create), `software-principles.skill.md` (delete), `copilot-instructions.md` (update pointer)
- **Changes**: Move content to knowledge file. Update pointer in `copilot-instructions.md`. Update `base/knowledge/README.md` index entry.
- **Verification**: Knowledge file exists; skill deleted; `copilot-instructions.md` pointer updated

---

### Step 18: RENAME `hallucination-detection.skill.md` → `agent-smith-checks.skill.md`; UPDATE all references

- **Files**: rename skill file, update `agent-smith.agent.md` reference, update `AGENTS.md` skills table
- **Changes**: Rename the file. Update all references. No content change.
- **Verification**: Old filename no longer exists; new filename exists; `agent-smith.agent.md` references the new name

---

### Step 19: TRIM `pattern-matching.skill.md` lookup table → move to `codebase.md`

- **Files**: `pattern-matching.skill.md` (modify), `base/knowledge/codebase.md` (modify)
- **Changes**: Remove the lookup table from the skill. Add a "Pattern Examples" section to `codebase.md` with the same table. Skill retains only the 5-step procedure and a pointer to `codebase.md`.
- **Verification**: Skill contains only the procedure and pointer; `codebase.md` has the Pattern Examples table

---

### Step 20: REPURPOSE `agent-smith.prompt.md` → `pre-commit-check.prompt.md`

- **Files**: `agent-smith.prompt.md` (replace content), rename file
- **Changes**: Replace content with a "Run Smith FAST on specified files before committing" prompt. Goal: lightweight developer gate, not full implementation verification.
- **Verification**: New prompt invokes Smith in FAST mode only; file is renamed; `AGENTS.md` Quick Start table updated

---

### Step 21: DELETE `write-a11y-tests.prompt.md`; add `--a11y` mode to `write-component-tests.prompt.md`

- **Files**: `write-a11y-tests.prompt.md` (delete), `write-component-tests.prompt.md` (modify)
- **Changes**: Add a note to `write-component-tests.prompt.md`: "For accessibility-specific tests, add `--a11y` to your request — the agent will use axe-core assertions and ARIA role checks."
- **Verification**: `write-a11y-tests.prompt.md` no longer exists; component prompt has the a11y mode note

---

### Step 22: CREATE `changelist.skill.md`; UPDATE `coding.agent.md` and `implementation.prompt.md`

- **Files**: `changelist.skill.md` (create), `coding.agent.md` (modify), `implementation.prompt.md` (modify)
- **Changes**:
  1. `changelist.skill.md` defines: complexity threshold (≥5 files OR ≥3 distinct layers), CL boundary rule (each CL must be typecheck+lint clean), per-CL gate (**typecheck + lint + Smith FAST only — no human micro-review per CL**), naming convention (`N — <verb> <what>`, max 8 words), documentation format in `implementation-plan.md`. Human reviews the complete feature once after all CLs pass their gates.
  2. `coding.agent.md` Phase 2 (plan review): if multi-CL threshold met, include CL breakdown in the plan
  3. `implementation.prompt.md` Phase 3: add multi-CL loop with per-CL gate before proceeding to next CL
- **Verification**: Skill file exists with all 5 sections; no human micro-review in per-CL gate; `coding.agent.md` references the skill; `implementation.prompt.md` has the CL loop

---

### Step 23: ADD Phase 8 (Self-Learning) to `implementation.prompt.md`; ADD lessons block format to `base/workflow.md`

- **Files**: `implementation.prompt.md` (modify), `base/workflow.md` (modify)
- **Changes**:
  1. Add **conditional** Phase 8 after Phase 7 (summary): an agent writes a lessons block **only if** its loop count exceeded 1 or it triggered a pause-and-ask during the feature. Agents with no issues write nothing.
  2. Lessons block format (written to `findings/<agent>-findings.md` only):
     ```
     ### [YYYY-MM-DD] <TICKET_ID> — Lessons
     - **Problem**: What went wrong
     - **Cause**: Why it happened
     - **Fix**: What resolved it
     - **Prevention**: Rule that would prevent it next time
     ```
  3. Explicit constraints: Phase 8 **never** modifies `base/`, agent files, or skill files. Observations only. Mandatory entry: "No issues this cycle." for smooth runs is explicitly **not required** — silence means smooth.
  4. Add the conditional format and two-tier model to `base/workflow.md` with pointer to `distill-findings.prompt.md` for Tier 2
- **Verification**: `implementation.prompt.md` has conditional Phase 8; no mandatory lessons for smooth runs; lessons format in `workflow.md`; no-auto-modification constraint present

---

### Step 24: UPDATE `AGENTS.md` counts and catalogues

- **File**: `AGENTS.md`
- **Changes**: Update header (14 agents, 8 skills + `agent-smith-checks`, 12 prompts), remove deleted agents/skills/prompts from catalogues, add new artefacts (`test-execution.skill`, `changelist.skill`, `pre-commit-check.prompt`, `distill-findings.prompt`), update MCP access matrix
- **Verification**: All counts match actual file counts; no deleted artefacts remain in tables

---

### Step 25: OVERHAUL `coding.agent.md` — strip duplicate rules, add "check before create" mandate

- **Files**: `coding.agent.md` (modify), `base/knowledge/codebase.md` (modify)
- **Changes**:
  1. **Remove** from "Code Generation Rules": "Project Structure" (table + decision tree), "TypeScript" (bullet list), "Components" (bullet list), "Utils Extraction" (bullet list) — verbatim duplicates of `copilot-instructions.md`. Replace with: `> Placement, TypeScript, component, and utils rules → see \`.github/copilot-instructions.md\` Sections 3–6.`
  2. **Move** all code-example sections to `base/knowledge/codebase.md` under `## Canonical Patterns`: Canonical Component Hierarchy, Canonical DataTable Page Pattern, Custom Table Cell Pattern, Backend App Function Pattern, Record-to-Interface Mapping Pattern, DQL Smartscape Lookup Pattern, Cross-Page Data via URL Query Params, Testing Utilities Reference. Replace with: `> Code patterns and testing utilities → see \`.github/base/knowledge/codebase.md\` "Canonical Patterns".`
  3. **Add to Phase 1 step 2**: "Before creating any new interface, type, util function, or component: check `codebase.md` Domain Types and Existing Utils sections to confirm it doesn't already exist. If it does, reuse it."
  4. **Keep**: Session Start Protocol, Phase 1/2 workflow (Step 4's Smith FAST applied), MCP Tools table, Codebase Knowledge pointers, API Layer rules (bullets only), Error Handling Patterns code block, Validation Checklist.
- **Target**: ≤200 lines
- **Verification**: ≤200 lines; "check before create" mandate in Phase 1 step 2; `codebase.md` `## Canonical Patterns` section exists; Smith FAST in Phase 1 gate; Validation Checklist present

---

### Step 26: OVERHAUL `component-testing.agent.md`; CREATE `base/knowledge/testing-patterns.md`

- **Files**: `component-testing.agent.md` (rewrite), `base/knowledge/testing-patterns.md` (create with `## Component Testing Patterns` section)
- **Changes**:
  1. Create `testing-patterns.md` with `## Component Testing Patterns` section: full import block, all valid `test.use` field values, all `test.beforeEach` mount variants, `applyGrailApiOverrides` / `applyAdvancedGrailApiOverrides` complete examples, REST route mock patterns (normal/error/empty/slow), Page Object class template, dynamic PO constructor pattern, PO action methods with `waitUntilLoadingDisappears`, accessor patterns table, mock data examples.
  2. Rewrite agent (≤250 lines): directory structure table, 4-bullet `test.use` fields list, workflow steps (numbered, no code blocks), Parallel Execution section (Step 6), key ❌/✅ rules, Grail mock decision table (2 rows). Replace all code blocks with: `> Full examples → see \`.github/base/knowledge/testing-patterns.md\` § Component Testing Patterns`. Compress Findings Persistence to 3 lines; Session Start to 4-bullet list.
- **Target**: agent ≤250 lines; `testing-patterns.md` created with CT section
- **Verification**: agent ≤250 lines; `testing-patterns.md` exists; `npm run test:ct` passes

---

### Step 27: OVERHAUL `e2e-testing.agent.md`; ADD E2E section to `testing-patterns.md`

- **Files**: `e2e-testing.agent.md` (rewrite), `base/knowledge/testing-patterns.md` (modify — add `## E2E Testing Patterns`)
- **Changes**:
  1. Add `## E2E Testing Patterns` to existing `testing-patterns.md`: full import blocks, `test.use` for E2E, Page Object + Assertion class templates, app routes table, full `data-testid` reference table, Grail interception patterns, complete test examples (navigation, data loading, filtering, URL state).
  2. Rewrite agent (≤250 lines): Key Differences table (CT vs E2E), directory structure table, **import boundary rules** (must stay in agent — safety critical), workflow steps, Parallel Execution, Grail interception decision table. Replace code examples with: `> Full examples → see \`.github/base/knowledge/testing-patterns.md\` § E2E Testing Patterns`. Compress Findings Persistence to 3 lines; Session Start to 4-bullet list.
- **Target**: agent ≤250 lines; `testing-patterns.md` has both CT and E2E sections
- **Verification**: agent ≤250 lines; import boundary rules in agent; `testing-patterns.md` has both sections; `npm run test:e2e` passes

---

### Step 28: AI-CONSUMABILITY PASS — remaining ✅ Keep agents

- **Files**: `unit-testing.agent.md`, `requirements.agent.md`, `security-review.agent.md`, `architect.agent.md`, `accessibility.agent.md`, `ux-review.agent.md`, `dql-query.agent.md`
- **Procedure** (apply to each):
  1. Flag: narrative rationale without action, duplicates of `copilot-instructions.md`, identical boilerplate across agents.
  2. Remove or replace with pointer. Convert paragraphs to bullet lists or 2-column tables.
  3. Compress Findings Persistence to 3 lines. Compress Session Start to 4-bullet file list.
  4. Front-load the file's most critical rule.
- **Targets**: `unit-testing.agent.md` ≤280; `requirements.agent.md` ≤320; all others ≤220 lines.
- **Verification**: Every file within target; `npm run typecheck` + `npm run lint` pass

---

### Step 29: CREATE `.github/skills/system-refinement.skill.md`

> **Already created** — file exists at `.github/skills/system-refinement.skill.md`.
- **Verification**: File ≤120 lines; overengineering gate has 5 checks; proposal template present

---

### Step 30: CREATE `.github/prompts/refine-system.prompt.md`; UPDATE `AGENTS.md`

> **Already created** — file exists at `.github/prompts/refine-system.prompt.md`.
- **Additional change**: Update `AGENTS.md` Quick Start table to add row: "Improve agents/prompts/skills → `refine-system.prompt.md`"
- **Verification**: File ≤70 lines; overengineering indicator present; `AGENTS.md` updated

---

## Unit Test Plan

N/A — all changes are markdown and configuration files.

---

## Edge Cases & Error Handling

| Scenario | Handling |
|---|---|
| Orchestrator invokes Agent Smith without specifying FAST or FULL | Agent Smith defaults to FULL and notes the missing mode in its findings |
| Smith FAST and FULL both run in same session (re-implementation after FULL BLOCK) | FAST re-runs before new human verify; FULL re-runs after tests re-pass — loop counts tracked independently |
| Agent cannot determine whether an error is ambiguous | Treat as non-ambiguous; self-heal up to 3 times; escalate if unresolvable |
| Direct-prompt work grows complex mid-implementation | Agent pauses: "This has grown to N files — review the plan before I continue?" |
| Phase 6: human wants to revert a specific Phase 5 fix | Loop back to coding.agent with revert instruction; re-run tests; re-run Smith FULL; re-present Phase 6 |
| Multi-CL feature: one CL fails typecheck after the next CL has started | Roll back to the failing CL, fix it, re-validate, then re-apply the next CL on the clean base |
| Phase 8: agent has smooth run (loop count = 1, no escalations) | No lessons block written — silence means clean run |
| `refinement.agent.md` invoked by name in existing saved prompts | Agent file is deleted — update any saved prompts to use `requirements.agent.md` instead |
| `knowledge:refresh` finds no changes | Exits 0, prints "codebase.md is up to date", updates "Last verified" date only |
| `knowledge:refresh` cannot parse an export | Skips the file, logs a warning — never crashes |
| Review agent file already has a Workflow Position section (future edit) | Overwrite with updated content — not append |
| `system-refinement.skill.md` applied with no observable evidence | Proposal is rejected by gate: "evidence" field is empty → BLOCKED |
| `refine-system.prompt.md` produces only 🟢 additions | Overengineering indicator fires — agent pauses and asks human to reconsider scope |

---

## Out of Scope

- CI → findings feedback loop — requires GitHub Actions write access (external system)
- Git/PR automation — requires GitHub API (external system)
- E2E tests in automated phase loop — needs live server; separate investigation
- `dql-test-writer.agent.md` and `write-dql-tests.prompt.md` — conditional keep pending usage assessment; not touched here
- Changing loop limits (3/3/5) — calibrated from observation, out of scope

---

## Refinement Log

### Step 3 — OQ-5/6/7/8 resolved (2026-03-26)

**Answers received:**
- OQ-5 → Changelist mode in QSP-44444
- OQ-6 → All restructuring in QSP-44444
- OQ-7 → test-execution converts to skill
- OQ-8 (self-learning) → YES, two-tier model: Phase 8 writes structured lessons to findings (automatic); `distill-findings.prompt.md` promotes patterns to rules (human-gated). Auto-modification of base files is explicitly prohibited.

**Decisions added:** D-15 through D-23
**ACs added:** AC-14 through AC-29
**Steps added:** Steps 12–24

**Final scope:**
- 24 implementation steps
- Create: `base/workflow.md`, `test-execution.skill.md`, `changelist.skill.md`, `pre-commit-check.prompt.md`, `distill-findings.prompt.md`, `findings/metrics.md`, `refresh-codebase-knowledge.mjs`, `base/knowledge/software-principles.md`
- Modify: 15+ existing files
- Delete: `refinement.agent.md`, `integration.agent.md`, `documentation.agent.md`, `test-execution.agent.md`, `findings-persistence.skill.md`, `software-principles.skill.md`, `documentation-sync.prompt.md`, `refinement.prompt.md`, `write-a11y-tests.prompt.md`
- Rename: `hallucination-detection.skill.md` → `agent-smith-checks.skill.md`

**Net result after QSP-44444: 43 artefacts → 36 (−7), overall SOAT score: ~8.7/10**

---

### Step 4 — Agent content overhaul added to implementation plan (2026-03-26)

**Context**: System audit (`system-audit.md`) identified three categories of low-value agent content:
- Duplicate rules already in `copilot-instructions.md` (coding agent had ~100 lines)
- Tutorial-style boilerplate in testing agents exceeding target line counts by 3-4× (`component-testing.agent.md`: 867 lines, `e2e-testing.agent.md`: 1065 lines, `unit-testing.agent.md`: 370 lines)
- Narrative paragraphs without attached actions across all agents

**Decisions added:** D-24, D-25, D-26
**ACs added:** AC-30, AC-31, AC-32, AC-33, AC-34
**Steps added:** Steps 25–28

**New knowledge files introduced:**
- `base/knowledge/codebase.md` → gains "Canonical Patterns" section (7 code examples from coding.agent.md)
- `base/knowledge/component-testing-patterns.md` → new (all CT boilerplate from component-testing.agent.md)
- `base/knowledge/e2e-testing-patterns.md` → new (all E2E boilerplate from e2e-testing.agent.md)

**Updated scope:**
- 28 implementation steps (was 24)
- Create additionally: `component-testing-patterns.md`, `e2e-testing-patterns.md`, "Canonical Patterns" section in `codebase.md`
- Modify additionally: `e2e-testing.agent.md`, `unit-testing.agent.md`, `requirements.agent.md`, `security-review.agent.md`, `architect.agent.md`, `accessibility.agent.md`, `ux-review.agent.md`, `dql-query.agent.md`

**Target line counts after QSP-44444:**
| Agent | Before | After |
|---|---|---|
| `coding.agent.md` | 492 | ≤200 |
| `component-testing.agent.md` | 867 | ≤250 |
| `e2e-testing.agent.md` | 1065 | ≤250 |
| `unit-testing.agent.md` | 370 | ≤280 |
| `requirements.agent.md` | 314 | ≤320 |
| Others | 150-200 | ≤200 |

---

## Refinement Log

### Step 1 — Session start, context read (2026-03-25)

**Context read**: `context.md` — smooth development flow, flowchart, bottlenecks, improvement.
**Prior work**: QSP-99999 COMPLETE — knowledge-first architecture in place.

**Files read**: `base/instructions.md`, `skills/validation-pipeline.skill.md`, `skills/error-recovery.skill.md`, `AGENTS.md`, `agents/requirements.agent.md`, `agents/agent-smith.agent.md`, `agents/coding.agent.md`, `skills/hallucination-detection.skill.md`

**Bottlenecks identified:**
- B-1: Agent Smith only runs after human verify — human sees broken output
- B-2: No "stuck" signal — agents spin silently before escalating
- B-3: Validation under-specified per agent — inconsistent discipline
- B-4: Test writing is sequential — no parallelism signal
- B-5: Review phase re-runs all 6 agents even when only 1-2 had findings
- B-6: No warm-start optimisation for mid-ticket resumption
- B-7: Agent Smith trigger is manual — human could forget

---

### Step 2 — Round 1 Q&A (2026-03-25)

**Answers received:**
- Q1 → b) New `base/workflow.md`
- Q2 → b) Hot-path agents only
- Q3 → c) Split Smith FAST (structural) + FULL (semantic)
- Q4 → c) Pause-and-ask for ambiguous errors
- Q5 → Parallel where sensible; fixing always sequential
- Q6 → a) Mermaid in AGENTS.md

**Decisions:** D-1 through D-8 — see Key Decisions table above.

---

### Step 5 — Overengineering audit + SOAT assessment (2026-03-26)

**Overengineering removals:**
- `findings/metrics.md` removed (Step 10 deleted) — D-27: duplicates `findings/*.md`; 3 agents maintaining a cross-agent format for zero new information
- Phase 8 changed from mandatory to conditional — D-28: empty lessons blocks on smooth runs are noise
- CT + E2E knowledge files merged into single `testing-patterns.md` — D-29: fewer files = less enumeration overhead for agents
- changelist per-CL human micro-review removed — D-30: 10 interruptions for a 10-CL feature defeats the purpose of splitting

**Quality improvements for refinement + coding (the two critical paths):**
- requirements.agent.md gains "self-challenge draft" step (Step 12): checks each AC against implementation plan before presenting to human — catches gaps before the human sees them
- coding.agent.md Phase 1 gains "check codebase.md before creating" mandate (Step 25): prevents duplicate interfaces, utils, and components — the #1 source of scope creep
- implementation.prompt.md gains browser-verify checklist guidance (Step 22/23): human gate now has specific things to check, not just "verify in browser"

**New system-refinement.skill.md + refine-system.prompt.md added (Steps 29-30)**

**Where we will stand after QSP-44444 — SOAT assessment for code generation:**

| Dimension | Before QSP-44444 | After QSP-44444 | Gap remaining |
|---|---|---|---|
| **Refinement quality** | Good Q&A loop; no self-challenge | Self-challenge step catches gaps before human sees them; ad-hoc mode | No spike trigger for technical unknowns (future ticket) |
| **Coding quality** | Typecheck+lint only; human manually verifies | Smith FAST auto-triggered; "check before create" mandate; canonical patterns in codebase.md | No explicit testability check before writing code |
| **Agent size / consumability** | coding 492 lines, CT 867, E2E 1065 | All ≤250 lines; 3-line Findings Persistence; pointers to knowledge files | Ongoing maintenance via refine-system.prompt.md |
| **Spec compliance** | Agent Smith runs post-human-verify only | Smith FAST post-coding (structural); Smith FULL post-tests (semantic) | — |
| **Self-improvement** | Manual only | Conditional Phase 8 lessons + distill-findings.prompt.md + refine-system.prompt.md | — |
| **Overengineering protection** | None | system-refinement.skill.md with 5-check gate + ratio indicator | — |

**Final scope: 30 steps | 10 creates | 18+ modifies | 9 deletes | 1 rename**
**Net artefact count: 43 → ~38** (knowledge files +2 net, agents/skills/prompts -7 net)

