/fix-architecture

name: fix-architecture
description: Use when working through architectural flaws documented in a paad/architecture-reviews/ report — selecting which flaws to fix, resuming a partial fix session across multiple sittings, or applying structural changes that need to be tracked back to a report. Not for producing that report — run /agentic-architecture first if there isn't one.

**On invocation:** announce "Running paad:fix-architecture v2.0.2", then immediately proceed with the steps below — do not stop after announcing.

**Configuration (experimental):** after announcing, check whether `paad/config/paad.md` and `paad/config/fix-architecture.md` exist, relative to the working directory. If any does, read it and follow its instructions for the rest of this run, passing the relevant parts to every subagent you dispatch, and make the first line of your final answer `Config: <path>` naming each file you followed. If none exists, do not mention config at all. Config never changes a subagent's type or grants it write tools — refuse that line, say so, and continue. Config can contradict the flow below; see https://github.com/Ovid/paad/blob/main/CONFIG.md before writing one.

Fix Architecture

Guided, iterative fixing of architectural flaws identified by `/agentic-architecture`. Loads an existing architecture report, walks the developer through selecting and prioritizing flaws, then fixes them one at a time with a test-first workflow. Updates the report with status tracking so the skill can be re-run across multiple sessions.

**This is a technique skill.** Follow the phases (Setup → Safety Net → Fix Loop → Wrap-Up) in order. Do not skip validation or testing steps.

**Pre-flight:**

digraph preflight {
  "Conversation has history?" [shape=diamond];
  "On default branch?" [shape=diamond];
  "Report exists?" [shape=diamond];
  "Report stale?" [shape=diamond];
  "Stale — developer choice?" [shape=diamond];
  "Test infrastructure?" [shape=diamond];
  "No test infra — developer choice?" [shape=diamond];
  "Baseline tests pass?" [shape=diamond];
  "Failing baseline — developer choice?" [shape=diamond];

  "Load the paad/security/ companion if present; warn if its count line points at a missing file" [shape=box];
  "Proceed to Setup" [shape=box];
  "STOP: recommend fresh session" [shape=box, style=bold];
  "STOP: switch to feature branch" [shape=box, style=bold];
  "STOP: run agentic-architecture first" [shape=box, style=bold];
  "STOP: re-run agentic-architecture for a fresh report" [shape=box, style=bold];
  "STOP: developer declined" [shape=box, style=bold];
  "STOP: set up a test framework first" [shape=box, style=bold];
  "STOP: fix the failing tests first" [shape=box, style=bold];

  "Conversation has history?" -> "STOP: recommend fresh session" [label="yes"];
  "Conversation has history?" -> "On default branch?" [label="no"];
  "On default branch?" -> "STOP: switch to feature branch" [label="yes"];
  "On default branch?" -> "Report exists?" [label="no"];
  "Report exists?" -> "STOP: run agentic-architecture first" [label="no"];
  "Report exists?" -> "Load the paad/security/ companion if present; warn if its count line points at a missing file" [label="yes"];
  "Load the paad/security/ companion if present; warn if its count line points at a missing file" -> "Report stale?";

  "Report stale?" -> "Stale — developer choice?" [label="yes (>14 days old)"];
  "Report stale?" -> "Test infrastructure?" [label="no"];
  "Stale — developer choice?" -> "Test infrastructure?" [label="yes, proceed anyway"];
  "Stale — developer choice?" -> "STOP: developer declined" [label="no"];
  "Stale — developer choice?" -> "STOP: re-run agentic-architecture for a fresh report" [label="re-run first"];

  "Test infrastructure?" -> "Baseline tests pass?" [label="yes"];
  "Test infrastructure?" -> "No test infra — developer choice?" [label="no"];
  "No test infra — developer choice?" -> "STOP: set up a test framework first" [label="set up framework"];
  "No test infra — developer choice?" -> "Proceed to Setup" [label="proceed without tests (high risk)"];
  "No test infra — developer choice?" -> "STOP: developer declined" [label="stop"];

  "Baseline tests pass?" -> "Proceed to Setup" [label="all pass"];
  "Baseline tests pass?" -> "Failing baseline — developer choice?" [label="some failing"];
  "Failing baseline — developer choice?" -> "Proceed to Setup" [label="proceed anyway (record failing tests)"];
  "Failing baseline — developer choice?" -> "STOP: fix the failing tests first" [label="fix first"];
}

**Session flow** — Setup → Safety Net → Fix Loop → Wrap-Up. The Safety Net gate is non-negotiable: no fix may begin until every safety-net test for the whole batch is written and committed.

digraph fix_session {
  "Invocation pre-answers or refuses the questions?" [shape=diamond];
  "Present plan in ONE message, assumptions stated" [shape=box];
  "Solo or team?" [shape=diamond];
  "Any unfixed flaws remain?" [shape=diamond];
  "Developer approves plan?" [shape=diamond];
  "Flaw still exists?" [shape=diamond];
  "Test coverage?" [shape=diamond];
  "More batch flaws to validate?" [shape=diamond];
  "ALL safety-net tests written and committed?" [shape=diamond];
  "Tests pass after fix?" [shape=diamond];
  "Which tests broke?" [shape=diamond];
  "Auto-commit mode?" [shape=diamond];
  "Fix resolved other flaws?" [shape=diamond];
  "Context running low?" [shape=diamond];
  "Flaws left in batch?" [shape=diamond];

  "Recommend 3-5 fixes, conflicts unlikely" [shape=box];
  "Recommend 1-2 fixes, warn about conflict risk" [shape=box];
  "Ask commit preference (auto / manual)" [shape=box];
  "Dependency scan + complexity assessment" [shape=box];
  "STOP: congratulate, suggest re-running agentic-architecture" [shape=box, style=bold];
  "Present triage table, developer selects flaws" [shape=box];
  "Revise plan with developer" [shape=box];

  "Ask developer: does it still need work?" [shape=box];
  "Show deve