gps-denied-onboard/.cursor/skills/refactor/phases/02-analysis.md

# Phase 2: Analysis & Task Decomposition

**Role**: Researcher, software architect, and task planner
**Goal**: Research improvements, produce a refactoring roadmap, and decompose into implementable tasks
**Constraints**: Analysis and planning only — no code changes

## 2a. Deep Research

1. Analyze current implementation patterns
2. Extract the **Project Constraint Matrix** from `problem.md`, `restrictions.md`, `acceptance_criteria.md`, current architecture/docs, and actual code constraints. Include required inputs/outputs, operating context, lifecycle assumptions, integration boundaries, non-functional targets, and hard disqualifiers.
3. Research modern approaches for similar systems
4. For each alternative pattern/library/service/architecture/algorithm, research intrinsic implementation constraints: required inputs/outputs, runtime assumptions, supported deployment modes, resource needs, operational limits, licensing/security constraints, and known failure reports.

   **API Capability Verification — Per-Mode (MANDATORY, BLOCKING for proposed replacements)**

   When a refactor recommendation replaces (or adds) a library/SDK/framework/service, the same per-mode verification used by `/research` Step 2 applies — selecting a replacement on category fit alone is the same silent-failure path. For every replacement candidate that has multiple modes or configurations:

   1. **Pin the exact mode/configuration** the refactored code will use, in one explicit sentence. Inputs (data shapes, sensor counts, payloads, rates), outputs (per `acceptance_criteria.md` and contract files), runtime (matching the project's deployment).
   2. **Run `context7` (or equivalent docs lookup)** for the candidate. **Mandatory for every replacement library/SDK/framework candidate**, not optional. Minimum three queries per candidate: mode enumeration, project's exact mode (with input/output shapes), disqualifier probe ("does this mode produce the required output? are there published limitations on this runtime?"). Append URLs to `RUN_DIR/analysis/research_findings.md` references section.
   3. **Save a Minimum Viable Example (MVE)** for the pinned mode under `RUN_DIR/analysis/mve_evidence.md` with: source, inputs in example, outputs in example, project inputs, project outputs required, match assessment ✅/⚠️/❌. If no official example covers the project's exact configuration, the recommendation cannot be `Selected` based on category fit alone — it must be `Experimental only` (with required-evidence note) or `Rejected`.
   4. **Treat "the same library in a different mode" as a different recommendation.** If the project's pinned mode is `<X>` but the only documented evidence covers `<Y>`, do not silently soften the description. Open a separate recommendation row, with its own MVE, fit assessment, and disqualifiers.
   5. **Common silent-failure pattern**: a fact summary paraphrases docs as "supports A, B, C, D modes" when the docs actually mean "supports A; B; C and D as separate orthogonal modes" — no `A+B` combination exists. Cross-check paraphrased capability claims against the literal mode enumeration.

5. Identify what could be done differently
6. Suggest improvements only when they fit the Project Constraint Matrix. A cleaner or more modern approach that violates product constraints must be marked `Rejected` or `Experimental only`, not added as a roadmap recommendation.

Write `RUN_DIR/analysis/research_findings.md`:
- Current state analysis: patterns used, strengths, weaknesses
- Alternative approaches per component: current vs alternative, pros/cons, migration effort
- Prioritized recommendations: quick wins + strategic improvements
- Constraint-fit table: recommendation, **pinned mode/config**, constraints checked, **API capability evidence (MVE link)**, evidence, mismatches/disqualifiers, status (`Selected` / `Rejected` / `Experimental only` / `Needs user decision`)
- For every recommendation that replaces or adds a library/SDK/framework, append a **Restrictions × Candidate-Mode sub-matrix** that walks every numbered line of `restrictions.md` and `acceptance_criteria.md` against the candidate's pinned mode, marking each cell ✅ Pass / ❌ Fail / ❓ Verify / N/A with cited evidence. A recommendation cannot be `Selected` while any cell is ❌ or ❓.

## 2b. Solution Assessment & Hardening Tracks

1. Assess current implementation against acceptance criteria
2. Identify weak points in codebase, map to specific code areas
3. Perform gap analysis: acceptance criteria vs current state
4. Prioritize changes by impact and effort
5. Reject or escalate any proposed refactor that improves code structure while weakening required behavior, integration contracts, runtime constraints, safety/security posture, or acceptance criteria

### 2b.1. ADR Superseding Gate (BLOCKING)

A refactor that improves code structure while overturning a documented architecture decision is the silent-drift class the project repeatedly burns on (see `meta-rule.mdc` § GPS-passthrough postmortem and the auto-lessons it produced). This gate makes drift visible and forces a deliberate ADR update.

1. **List candidate ADRs**: read every `Status: Accepted` file in `_docs/02_document/adr/`. If the directory does not exist or contains only the index, log `No ADRs in scope` to `RUN_DIR/analysis/adr_impact.md` and skip the rest of this gate.
2. **Diff each candidate against the proposed refactor roadmap**: for each ADR, ask the same two questions as code-review Phase 7:
   - **Violation**: does any roadmap item do the *opposite* of the ADR's `Decision`?
   - **Drift**: does any roadmap item materially affect the ADR's `Consequences` (positive or negative) without contradicting the Decision outright?
3. **Classify each impacted ADR** in `RUN_DIR/analysis/adr_impact.md`:

   | ADR | Roadmap item | Impact | Required action |
   |-----|--------------|--------|-----------------|
   | NNN | `roadmap-item-NN` | Violation / Drift / Aligned | (filled by Choose A/B/C below) |

4. **For every Violation row, present a BLOCKING Choose**:

   ```
   ══════════════════════════════════════
    DECISION REQUIRED: Refactor would violate ADR-NNN (<title>)
   ══════════════════════════════════════
    A) Update the ADR via supersede: the refactor produces a NEW ADR
       (`Supersedes: NNN`) capturing the new Decision, and ADR-NNN's
       `Superseded by` field is updated. The supersede ADR is itself a
       deliverable of this refactor run (added to RUN_DIR/analysis/adr_impact.md
       and to TASKS_DIR as a task) and must be `Accepted` before Phase 4.
    B) Reduce the refactor scope to NOT violate ADR-NNN
    C) Re-evaluate ADR-NNN: keep the refactor but only after ADR-NNN is
       formally re-opened in a new /plan Step 4.5 round
   ══════════════════════════════════════
    Recommendation: A — supersede is the only path that keeps the audit
    trail intact while letting the refactor land
   ══════════════════════════════════════
   ```

5. **For every Drift row**: do not block, but the roadmap item must include a `## ADR Impact` section in its task spec citing the affected ADR(s). The implementer surfaces this at code-review Phase 7, which would otherwise classify the change as ADR-Drift (High) without context.
6. **For every Aligned row**: cite the ADR in the roadmap item's task spec under `## ADR Compliance`. No further action.
7. **Self-supersede deliverable**: any Choose A path adds a `[##]_supersede_adr_NNN.md` task file to the refactor run's TASKS_DIR with the new ADR text drafted (using `.cursor/skills/plan/templates/adr.md`). The task's only Acceptance Criterion is "ADR file exists at `_docs/02_document/adr/<next>_<slug>.md` with `Status: Accepted`, ADR-NNN's `Superseded by` field updated, and `_docs/02_document/adr/README.md` index reflects both."

Present optional hardening tracks for user to include in the roadmap:

```
══════════════════════════════════════
 DECISION REQUIRED: Include hardening tracks?
══════════════════════════════════════
 A) Technical Debt — identify and address design/code/test debt
 B) Performance Optimization — profile, identify bottlenecks, optimize
 C) Security Review — OWASP Top 10, auth, encryption, input validation
 D) All of the above
 E) None — proceed with structural refactoring only
══════════════════════════════════════
```

For each selected track, add entries to `RUN_DIR/list-of-changes.md` (append to the file produced in Phase 1):
- **Track A**: tech debt items with location, impact, effort
- **Track B**: performance bottlenecks with profiling data
- **Track C**: security findings with severity and fix description

Write `RUN_DIR/analysis/refactoring_roadmap.md`:
- Weak points assessment: location, description, impact, proposed solution
- Gap analysis: what's missing, what needs improvement
- Phased roadmap: Phase 1 (critical fixes), Phase 2 (major improvements), Phase 3 (enhancements)
- Selected hardening tracks and their items
- Applicability gate: each roadmap item must state constraint fit, mismatches, required evidence, and status (`Selected` / `Rejected` / `Experimental only` / `Needs user decision`)

**BLOCKING applicability gate**: Before 2c and 2d, every recommendation in the roadmap must be `Selected`. Items marked `Rejected` are excluded. Items marked `Experimental only` or `Needs user decision` require a user decision before task creation.

**BLOCKING ADR-supersede gate**: Before 2c and 2d, every Violation row in `RUN_DIR/analysis/adr_impact.md` (from 2b.1) must be resolved via Choose A, B, or C. A Violation row with no chosen path blocks task creation.

## 2c. Create Epic

Create a work item tracker epic for this refactoring run:

1. Epic name: the RUN_DIR name (e.g., `01-testability-refactoring`)
2. Create the epic via configured tracker MCP
3. Record the Epic ID — all tasks in 2d will be linked under this epic
4. If tracker is unavailable, follow `.cursor/rules/tracker.mdc`; only use `PENDING` placeholders if the user explicitly chooses `tracker: local`

## 2d. Task Decomposition

Convert the finalized `RUN_DIR/list-of-changes.md` into implementable task files.

1. Read `RUN_DIR/list-of-changes.md`
2. For each change entry (or group of related entries), create an atomic task file in TASKS_DIR:
   - Use the standard task template format (`.cursor/skills/decompose/templates/task.md`)
   - File naming: `[##]_refactor_[short_name].md` (temporary numeric prefix)
   - **Task**: `PENDING_refactor_[short_name]`
   - **Description**: derived from the change entry's Problem + Change fields
   - **Complexity**: estimate 1-5 points; split into multiple tasks if >5
   - **Dependencies**: map change-level dependencies (C01, C02) to task-level tracker IDs
   - **Component**: from the change entry's File(s) field
   - **Epic**: the epic created in 2c
   - **Acceptance Criteria**: derived from the change entry — verify the problem is resolved
3. Create work item ticket for each task under the epic from 2c
4. Rename each file to `[TRACKER-ID]_refactor_[short_name].md` after ticket creation
5. Update or append to `TASKS_DIR/_dependencies_table.md` with the refactoring tasks

**Self-verification**:
- [ ] All acceptance criteria are addressed in gap analysis
- [ ] Recommendations are grounded in actual code, not abstract
- [ ] Every recommendation has been checked against the Project Constraint Matrix
- [ ] No recommendation violates product restrictions, acceptance criteria, documented architecture decisions, or actual code integration boundaries
- [ ] Every replacement library/SDK/framework recommendation has a pinned mode/config, a saved MVE in `mve_evidence.md`, and a Restrictions × Candidate-Mode sub-matrix with no ❌ or ❓ cells
- [ ] `context7` (or equivalent) was consulted for every replacement library/SDK/framework recommendation
- [ ] Paraphrased capability claims have been cross-checked against the literal mode-enumeration evidence (no `A, B → A+B` style conflation)
- [ ] Rejected and experimental approaches are documented but not converted into implementation tasks without user approval
- [ ] Roadmap phases are prioritized by impact
- [ ] Epic created and all tasks linked to it
- [ ] Every entry in list-of-changes.md has a corresponding task file in TASKS_DIR
- [ ] No task exceeds 5 complexity points
- [ ] Task dependencies are consistent (no circular dependencies)
- [ ] `_dependencies_table.md` includes all refactoring tasks
- [ ] Every task has a work item ticket (or PENDING placeholder)
- [ ] If `_docs/02_document/adr/` exists with Accepted ADRs, `RUN_DIR/analysis/adr_impact.md` has been written and every Violation row is resolved (A/B/C) — no implicit overrides
- [ ] For every Violation resolved via Choose A, a `[##]_supersede_adr_NNN.md` task exists in TASKS_DIR with the drafted supersede ADR
- [ ] For every Drift row, the corresponding roadmap-item task spec has a `## ADR Impact` section
- [ ] For every Aligned row, the corresponding roadmap-item task spec has a `## ADR Compliance` section

**Save action**: Write analysis artifacts to RUN_DIR, task files to TASKS_DIR

**BLOCKING**: Present refactoring roadmap and task list to user. Do NOT proceed until user confirms.

**Quick Assessment mode stops here.** Present final summary and write `FINAL_report.md` with phases 0-2 content.