@jetrabbits/agentic 0.0.1

package/areas/software/backend/skills/troubleshooting/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: troubleshooting
+type: skill
+description: Systematic backend debugging — reproduce, isolate root cause, implement fix with regression test.
+related-rules:
+  - architecture.md
+  - testing.md
+allowed-tools: Read, Write, Edit, Bash, Grep
+---
+
+# Troubleshooting Skill
+
+> **Expertise:** Systematic debugging, log analysis, query profiling, memory/CPU profiling, regression tests.
+
+## Debugging Framework (RRCA)
+
+```
+1. REPRODUCE — make the bug happen reliably before touching code
+2. REDUCE    — find the smallest input that triggers the bug
+3. CAUSE     — identify the specific code line/condition responsible
+4. ADDRESS   — fix + regression test + verify fix doesn't reappear
+```
+
+Never fix what you can't reproduce. A guess-and-check fix is technical debt.
+
+## Log Analysis Patterns
+
+```bash
+# Find all errors in last hour (structured logs with jq)
+journalctl -u myapp --since "1 hour ago" | jq 'select(.level == "error")'
+
+# Count errors by type
+cat app.log | jq -r '.error_code' | sort | uniq -c | sort -rn | head -20
+
+# Find slowest requests
+cat access.log | jq 'select(.duration > 1000)' | jq -r '[.method, .path, .duration] | @csv'
+
+# Trace a specific request by request_id
+grep "request_id=req_abc123" app.log
+
+# Find N+1 patterns: same query repeated many times in same request
+grep "request_id=req_abc123" app.log | grep "db.query" | wc -l  # > 10 is suspicious
+```
+
+## Database Query Debugging
+
+```sql
+-- Show currently running queries (PostgreSQL)
+SELECT pid, now() - pg_stat_activity.query_start AS duration, query, state
+FROM pg_stat_activity
+WHERE state != 'idle' AND query_start < now() - interval '5 seconds'
+ORDER BY duration DESC;
+
+-- Kill a blocking query
+SELECT pg_terminate_backend(<pid>);
+
+-- Find slow queries from pg_stat_statements
+SELECT query, calls, mean_exec_time, total_exec_time
+FROM pg_stat_statements
+ORDER BY total_exec_time DESC LIMIT 10;
+
+-- Check for table bloat (after many deletes/updates)
+SELECT relname, n_dead_tup, n_live_tup,
+       round(n_dead_tup * 100.0 / nullif(n_live_tup + n_dead_tup, 0), 2) AS dead_pct
+FROM pg_stat_user_tables
+WHERE n_dead_tup > 1000
+ORDER BY dead_pct DESC;
+```
+
+## Memory Leak Detection (Python)
+
+```python
+# Detect growing memory with tracemalloc
+import tracemalloc
+
+tracemalloc.start()
+
+# ... run suspected code ...
+
+snapshot = tracemalloc.take_snapshot()
+top_stats = snapshot.statistics("lineno")
+for stat in top_stats[:10]:
+    print(stat)  # shows file:line and allocated bytes
+
+# Typical culprits:
+# - Unbounded in-memory caches (dict that grows forever)
+# - Event listeners not being removed
+# - Circular references preventing GC
+```
+
+## HTTP Client Debugging
+
+```python
+import httpx
+import logging
+
+# Enable full request/response logging for debugging
+logging.basicConfig(level=logging.DEBUG)
+httpx_logger = logging.getLogger("httpx")
+httpx_logger.setLevel(logging.DEBUG)
+
+# Or manually log request details
+async with httpx.AsyncClient() as client:
+    response = await client.post(url, json=payload, timeout=30.0)
+    print(f"Request: {response.request.method} {response.request.url}")
+    print(f"Request body: {response.request.content}")
+    print(f"Status: {response.status_code}")
+    print(f"Response: {response.text[:500]}")
+```
+
+## Writing Regression Tests
+
+```python
+# Pattern: test must FAIL before the fix, PASS after
+# Step 1: reproduce as a test
+def test_order_creation_with_zero_quantity_raises_validation_error():
+    """Regression: order with zero quantity was silently accepted (bug PROJ-198)"""
+    with pytest.raises(ValidationError) as exc_info:
+        CreateOrderRequest(items=[{"product_id": "prod_1", "quantity": 0}])
+
+    assert "quantity" in str(exc_info.value)
+    assert "greater than 0" in str(exc_info.value)
+
+# Step 2: run test — it should FAIL on current code
+# Step 3: implement fix
+# Step 4: run test — it should now PASS
+# Step 5: run full suite to confirm no regressions
+```
+
+## Common Root Cause Patterns
+
+| Symptom | Likely cause | Investigation |
+|---|---|---|
+| Intermittent 500s after deploy | Exception in new code path | Check error logs at deploy time; git diff |
+| Slow requests on specific endpoint | N+1 query or missing index | EXPLAIN ANALYZE on DB queries in that request |
+| Memory grows over time | Cache without TTL or eviction | tracemalloc; check dict/list sizes in long-running processes |
+| Random 429s from upstream | No retry-after respect; burst traffic | Check outbound request rate; add backoff |
+| Test passes locally, fails in CI | Env var missing; timing issue | Compare env vars; add explicit waits |
+| Occasional duplicate records | Missing idempotency key or DB unique constraint | Add unique constraint; add idempotency check |

package/areas/software/backend/workflows/add-migration.md

@@ -0,0 +1,79 @@
+---
+name: add-migration
+type: workflow
+trigger: /add-migration
+description: Plan, implement, and validate safe schema migrations using expand/contract principles.
+inputs:
+  - schema_change_request
+  - affected_services
+outputs:
+  - migration_artifacts
+  - validation_report
+roles:
+  - team-lead
+  - developer
+  - qa
+execution:
+  initiator: team-lead
+related-rules:
+  - data_access.md
+  - architecture.md
+  - testing.md
+uses-skills:
+  - database-modeling
+  - troubleshooting
+quality-gates:
+  - forward migration validated on test DB
+  - rollback or mitigation strategy documented
+  - no blocking backward-compatibility risk for running services
+---
+
+## Steps
+
+### 1. Risk & Compatibility Analysis — `@team-lead`
+- **Input:** schema change request + list of affected services
+- **Actions:**
+  - classify change: non-breaking (add nullable column, add index) vs. breaking (rename/drop column, change type, add NOT NULL)
+  - for breaking changes: require expand/contract — two-phase migration across separate deployments
+  - identify all consumers of the affected table/column; confirm backward-compatibility window
+  - document rollback plan or mitigation (feature flag, dual-read window)
+- **Output:** migration strategy doc: phases, compatibility window, rollback plan
+- **Done when:** strategy approved; no services will break on forward migration
+
+### 2. Migration Implementation — `@developer`
+- **Input:** approved migration strategy
+- **Actions:**
+  - write migration script (Alembic, Flyway, Liquibase, etc.) following project conventions
+  - Phase 1 (expand): add new column/table as nullable or with default; keep old structure intact
+  - ensure migration is idempotent and reversible (`upgrade` + `downgrade` both implemented)
+  - update application code to write to both old and new structures during transition if needed
+- **Output:** migration file + updated application code on feature branch
+- **Done when:** migration runs cleanly on local test DB; `downgrade` also verified
+
+### 3. Test DB Validation & Data Checks — `@qa`
+- **Input:** migration file + test DB
+- **Actions:**
+  - run `upgrade` on a copy of the test DB; verify schema matches expected state
+  - run `downgrade`; verify clean revert with no data loss
+  - execute affected queries and check index usage (EXPLAIN ANALYZE)
+  - validate row counts and data integrity on key tables post-migration
+- **Output:** `validation_report.md` — migration results, query plans, data integrity checks
+- **Done when:** both directions validated; no unexpected data loss or performance degradation
+
+### 4. Review & Remediation Loop — `@team-lead` + `@developer`
+- **Input:** validation report
+- **Actions:** `@team-lead` reviews migration SQL and application changes; flags any issues; `@developer` fixes and re-runs validation
+- **Output:** approved migration
+- **Done when:** `@team-lead` approves; no open issues in validation report
+
+### 5. Readiness Report — `@pm` (or `@team-lead` if PM absent)
+- **Input:** approved migration + validation report
+- **Actions:** confirm deployment sequence (migrate before or after app rollout); document rollback command; note monitoring signals to watch post-deploy
+- **Output:** `migration_readiness.md` with deployment steps, rollback command, monitoring checklist
+- **Done when:** ops/release team has everything needed to deploy safely
+
+## Iteration Loop
+If validation reveals data issues or compatibility risks → return to Step 1 for strategy revision.
+
+## Exit
+Validated migration + readiness report + `@team-lead` approval = ready to deploy.

package/areas/software/backend/workflows/create-endpoint.md

@@ -0,0 +1,89 @@
+---
+name: create-endpoint
+type: workflow
+trigger: /create-endpoint
+description: Implement a new API endpoint with contract, security, and test coverage.
+inputs:
+  - endpoint_scope
+  - api_contract
+  - non_functional_requirements
+outputs:
+  - production_ready_endpoint
+  - tests_and_review_evidence
+roles:
+  - product-owner
+  - pm
+  - team-lead
+  - developer
+  - qa
+execution:
+  initiator: product-owner
+related-rules:
+  - architecture.md
+  - data_access.md
+  - security.md
+  - testing.md
+uses-skills:
+  - api-design
+  - database-modeling
+  - troubleshooting
+quality-gates:
+  - API contract approved before implementation
+  - security checks passed (auth, input validation, rate limiting)
+  - automated tests green
+---
+
+## Steps
+
+### 1. Scope & Contract — `@product-owner` + `@pm`
+- **Input:** endpoint request
+- **Actions:** define HTTP method, path, request/response schema, error codes, auth requirements, non-goals
+- **Output:** API contract doc or OpenAPI snippet in `docs/<feature>/api-contract.md`
+- **Done when:** contract is unambiguous and approved
+
+### 2. Architecture Review — `@team-lead`
+- **Input:** API contract
+- **Actions:** verify contract aligns with existing API conventions (per `api-design` skill); confirm data model impact; identify performance and security risks (N+1, injection surface, auth scope); approve or request changes
+- **Output:** architecture approval + notes on risks
+- **Done when:** `@team-lead` approves; implementation approach clear
+
+### 3. Implementation — `@developer`
+- **Input:** approved contract + architecture notes
+- **Actions:**
+  - update schemas/DTOs for input validation (Pydantic, Joi, etc.)
+  - implement repository method if new DB query needed — check indexes
+  - implement service layer logic with error handling and business rules
+  - wire API layer: route, auth middleware, response serialization
+  - do not put business logic in the API handler
+- **Output:** endpoint implemented on feature branch
+- **Done when:** endpoint handles all contract scenarios; no lint errors
+
+### 4. Test Design & Execution — `@qa`
+- **Input:** implemented endpoint + API contract
+- **Actions:**
+  - write integration tests covering: happy path, validation errors (400), auth errors (401/403), not-found (404), edge cases
+  - verify input sanitization and auth enforcement manually
+  - check response schema matches contract
+- **Output:** test suite passing; `docs/<feature>/test_report.md`
+- **Done when:** all contract scenarios tested and passing; security checks confirmed
+
+### 5. Code Review & Sign-off — `@team-lead`
+- **Input:** feature branch + test report
+- **Actions:** verify layering rules respected; check error handling completeness; confirm observability (request logged, errors traced); provide feedback as blocking / non-blocking
+- **Output:** review feedback (PR comments or `review_feedback.md`)
+- **Done when:** all blocking comments resolved; `@team-lead` approves
+
+### 6. Fix / Retest Loop — `@developer` + `@qa`
+- **Input:** blocking feedback
+- **Actions:** fix issues; re-run tests; re-request review
+- **Output:** updated branch
+- **Done when:** zero blocking issues; tests green
+
+### 7. Acceptance — `@product-owner` + `@pm`
+- **Input:** verified endpoint + test evidence
+- **Actions:** `@product-owner` confirms endpoint meets business need; `@pm` records delivery notes
+- **Output:** endpoint accepted; delivery note in `docs/<feature>/delivery_summary.md`
+- **Done when:** `@product-owner` signs off
+
+## Exit
+Accepted endpoint + passing tests + `@team-lead` sign-off = ready to merge.

package/areas/software/backend/workflows/debug-issue.md

@@ -0,0 +1,77 @@
+---
+name: debug-issue
+type: workflow
+trigger: /debug-issue
+description: Resolve backend defects with reproducible diagnosis, verified fix, and root cause documentation.
+inputs:
+  - incident_or_bug_report
+  - logs_metrics_traces
+outputs:
+  - verified_fix
+  - root_cause_summary
+roles:
+  - pm
+  - team-lead
+  - developer
+  - qa
+execution:
+  initiator: pm
+related-rules:
+  - architecture.md
+  - security.md
+  - testing.md
+uses-skills:
+  - observability
+  - troubleshooting
+quality-gates:
+  - issue reproducible before fix is written
+  - fix verified by automated checks and regression test
+  - root cause documented with prevention note
+---
+
+## Steps
+
+### 1. Triage & Impact Classification — `@pm` + `@team-lead`
+- **Input:** bug report or incident alert
+- **Actions:** confirm business impact and affected users; classify severity (P0 critical / P1 high / P2 normal); assign owner; set expected resolution time
+- **Output:** severity label + assigned owner + ETA in ticket
+- **Done when:** severity agreed; `@developer` assigned and briefed
+
+### 2. Reproduce & Isolate — `@developer`
+- **Input:** bug report + logs/metrics/traces (use `observability` skill to query)
+- **Actions:**
+  - reproduce the issue in a local or staging environment — do not fix without reproducing first
+  - narrow to the smallest reproducible case
+  - identify the code path: which layer (API / service / repository / infra)?
+  - check recent commits touching that area: `git log -p -- <file>`
+- **Output:** confirmed reproduction steps + suspected root cause hypothesis
+- **Done when:** issue reliably reproducible; root cause narrowed to a specific code area
+
+### 3. Fix Implementation — `@developer`
+- **Input:** reproduction + root cause hypothesis
+- **Actions:**
+  - write a failing regression test first (proves the bug exists)
+  - implement the minimal fix that makes the test pass
+  - check for related occurrences of the same pattern elsewhere in the codebase
+  - run full test suite to confirm no regressions: `make test`
+- **Output:** fix + regression test on feature branch; all tests passing
+- **Done when:** regression test passes; full suite green; fix is minimal and safe
+
+### 4. Verification & Regression Checks — `@qa`
+- **Input:** fix branch
+- **Actions:**
+  - reproduce original issue with fix applied — confirm resolved
+  - run regression test suite on affected module
+  - perform exploratory checks on related functionality
+  - verify fix in staging environment if P0/P1
+- **Output:** `verification_report.md` — confirmed fix, regression results, env tested
+- **Done when:** issue resolved in all tested environments; no new failures introduced
+
+### 5. Technical Review & Closure — `@team-lead`
+- **Input:** fix branch + verification report
+- **Actions:** review fix for correctness and side effects; confirm root cause analysis is complete; check that regression test is sufficient; write or approve `root_cause_summary.md` with prevention note
+- **Output:** `root_cause_summary.md` — what failed, why, how fixed, how to prevent
+- **Done when:** `@team-lead` approves fix; root cause documented; ticket closed
+
+## Exit
+Merged fix + verified resolution + root cause documented = incident closed.

package/areas/software/backend/workflows/develop-epic.md

@@ -0,0 +1,78 @@
+---
+name: develop-epic
+type: workflow
+trigger: /develop-epic
+description: Deliver a large multi-increment backend epic with controlled milestones and replanning.
+inputs:
+  - epic_goals
+  - prioritized_backlog
+outputs:
+  - incrementally_delivered_epic
+  - decision_and_risk_log
+roles:
+  - product-owner
+  - pm
+  - team-lead
+  - developer
+  - qa
+execution:
+  initiator: product-owner
+related-rules:
+  - architecture.md
+  - data_access.md
+  - security.md
+  - testing.md
+uses-skills:
+  - api-design
+  - async-processing
+  - observability
+  - troubleshooting
+quality-gates:
+  - each increment is independently testable and deployable
+  - integration and regression checks pass after each increment
+  - epic acceptance criteria satisfied before final sign-off
+---
+
+## Steps
+
+### 1. Epic Decomposition & Milestone Planning — `@product-owner` + `@pm`
+- **Input:** epic goals and high-level backlog
+- **Actions:** decompose epic into independently deliverable increments (max 1–2 weeks each); define milestone acceptance criteria; prioritize increments by value and risk; identify inter-increment dependencies
+- **Output:** `docs/<epic>/epic_plan.md` — increment list, acceptance criteria per increment, dependency map
+- **Done when:** `@product-owner` approves scope; `@pm` has a delivery sequence
+
+### 2. Architecture Runway Definition — `@team-lead`
+- **Input:** epic plan
+- **Actions:** identify shared infrastructure needed across increments (DB schema, shared services, API contracts); design the architecture runway — foundational work that must precede feature increments; document module layout and inter-service contracts; flag risks and non-functional requirements (performance, security, scalability)
+- **Output:** `docs/<epic>/architecture_notes.md` — layering decisions, migration plan, risk register
+- **Done when:** architecture runway approved; `@developer` can start Increment 1
+
+### 3. Increment Implementation — `@developer`
+- **Input:** increment spec from epic plan + architecture notes
+- **Actions:** implement current increment per `/develop-feature` workflow (Steps 3–5 of that workflow); each increment must have its own branch, tests, and acceptance evidence; do not start next increment without current one passing verification
+- **Output:** implemented increment on branch with passing checks
+- **Done when:** increment passes local checks and is ready for QA
+
+### 4. Increment Verification — `@qa`
+- **Input:** implemented increment
+- **Actions:** verify acceptance criteria for the current increment; run regression tests against all previously merged increments; document any cross-increment integration issues
+- **Output:** increment test report; integration risk notes if any
+- **Done when:** increment accepted; no regressions introduced
+
+### 5. Milestone Review & Replanning — `@pm` + `@team-lead`
+- **Input:** completed increment(s) + integration risk notes
+- **Actions:** review progress against epic plan; replan remaining increments based on learnings; update risk register; communicate status to `@product-owner`; adjust scope if needed (add/drop items with `@product-owner` approval)
+- **Output:** updated `epic_plan.md`; `risk_register.md` updated; stakeholders informed
+- **Done when:** next increment is prioritized and `@developer` is briefed
+
+### 6. Final Acceptance — `@product-owner`
+- **Input:** all increments delivered + complete risk summary
+- **Actions:** validate all epic acceptance criteria are met; review risk register for residual items; make go/defer decision on any remaining scope
+- **Output:** `docs/<epic>/delivery_summary.md` — accepted items, deferred items, follow-up backlog
+- **Done when:** epic accepted; follow-up items logged
+
+## Iteration Loop
+Steps 3–5 repeat for each increment. Replanning in Step 5 governs scope adjustments.
+
+## Exit
+All increments accepted by `@product-owner` + clean regression suite = epic delivered.

package/areas/software/backend/workflows/develop-feature.md

@@ -0,0 +1,98 @@
+---
+name: develop-feature
+type: workflow
+trigger: /develop-feature
+description: End-to-end backend feature delivery from requirements to accepted increment.
+inputs:
+  - feature_request
+  - acceptance_criteria
+outputs:
+  - delivered_feature
+  - release_readiness_report
+roles:
+  - product-owner
+  - pm
+  - team-lead
+  - developer
+  - qa
+  - designer  
+execution:
+  initiator: product-owner
+related-rules:
+  - architecture.md
+  - data_access.md
+  - security.md
+  - testing.md
+uses-skills:
+  - api-design
+  - async-processing
+  - observability
+quality-gates:
+  - scope and acceptance criteria approved before implementation
+  - all automated checks pass (lint / test / build)
+  - no unresolved blocking defects
+---
+
+## Steps
+
+### 1. Requirements & Value Framing — `@product-owner` + `@pm`
+- **Input:** feature request from stakeholder or backlog
+- **Actions:** define problem statement, expected outcomes, acceptance criteria, non-goals; confirm scope is implementation-ready
+- **Output:** `docs/<feature>/README.md` with acceptance criteria
+- **Done when:** criteria are testable and approved by `@product-owner`
+
+### 2. Solution Design & Risk Plan — `@team-lead` + `@designer`
+- **Input:** approved acceptance criteria
+- **Actions:** identify impacted domain entities and service boundaries; design API contracts and data model changes; define UX states and interaction constraints; flag security and performance risks; confirm approach with `@developer` for feasibility
+- **Output:** `docs/<feature>/implementation_plan.md` — layers affected, risks, migration notes if any
+- **Done when:** `@team-lead` and `@designer` approve plan; no open architecture blockers
+
+### 3. Implementation — `@developer`
+- **Input:** approved implementation plan
+- **Actions:**
+  - implement changes layer by layer (inner to outer): models/schemas → repository → service → API
+  - follow architecture rule: no business logic in API layer, no DB access in service layer directly
+  - add or update unit tests alongside implementation
+  - run `make lint && make test` locally before handoff
+- **Output:** code changes on feature branch with passing local checks
+- **Done when:** all acceptance criteria implemented; local checks green
+
+### 4. Risk-Based Verification — `@qa`
+- **Input:** feature branch + acceptance criteria
+- **Actions:**
+  - design test scenarios covering happy path, edge cases, failure paths
+  - execute automated tests (unit + integration); run exploratory checks for acceptance criteria
+  - verify security constraints (auth, input validation) per `security.md`
+  - document findings with severity classification
+- **Output:** `docs/<feature>/test_report.md` — pass/fail per scenario, defect list
+- **Done when:** no critical or high-severity open defects
+
+### 5. Code Review & Architecture Sign-off — `@team-lead`
+- **Input:** feature branch + test report
+- **Actions:** review layering and dependency rules; check test coverage quality; verify observability (logs, metrics, traces per `observability` skill); provide feedback as blocking / non-blocking
+- **Output:** `review_feedback.md` or inline PR comments
+- **Done when:** `@team-lead` approves; all blocking comments resolved
+
+### 6. Fix / Retest Loop — `@developer` + `@qa` (coordinated by `@pm`)
+- **Input:** blocking feedback list
+- **Actions:** `@developer` fixes; `@qa` retests affected scenarios; loop until no open blockers
+- **Output:** updated code + updated test report
+- **Done when:** zero open blocking issues
+
+### 7. Acceptance & Final Report — `@product-owner` + `@pm`
+- **Input:** verified increment + risk summary
+- **Actions:** `@product-owner` validates acceptance criteria; `@pm` produces delivery summary with decisions and follow-ups
+- **Output:** `docs/<feature>/delivery_summary.md` — accepted / deferred with rationale
+- **Done when:** feature accepted or explicitly deferred
+
+## Iteration Loop
+Steps 3–6 repeat per increment for large features. `@pm` tracks scope changes and timeline impact.
+
+## Mandatory Role Delegation
+- For `/develop-feature`, the executor must spawn exactly 6 subagents, one per role: `@product-owner`, `@pm`, `@team-lead`, `@developer`, `@qa`, `@designer`.
+- Role consolidation is forbidden: one subagent cannot own multiple roles.
+- Implementation work may start only after requirements outputs from `@product-owner` and `@pm`, and design outputs from `@team-lead` and `@designer`, are complete.
+- Final delivery requires QA recommendation and team-lead sign-off.
+
+## Exit
+`@product-owner` acceptance + no unresolved blockers = feature complete and ready for release.

package/areas/software/backend/workflows/refactor-module.md

@@ -0,0 +1,73 @@
+---
+name: refactor-module
+type: workflow
+trigger: /refactor-module
+description: Safely refactor backend modules with behavior parity guarantee and no functional regressions.
+inputs:
+  - refactor_goal
+  - baseline_behavior
+outputs:
+  - refactored_module
+  - behavior_parity_evidence
+roles:
+  - team-lead
+  - developer
+  - qa
+execution:
+  initiator: team-lead
+related-rules:
+  - architecture.md
+  - testing.md
+uses-skills:
+  - troubleshooting
+  - observability
+quality-gates:
+  - behavior baseline captured before refactor begins
+  - no regressions on critical flows
+  - complexity reduced or maintainability measurably improved
+---
+
+## Steps
+
+### 1. Refactor Plan & Boundaries — `@team-lead`
+- **Input:** refactor goal (e.g. extract service layer, reduce coupling, eliminate duplication)
+- **Actions:** define exact scope boundaries — what changes and what does NOT change; identify all callers/consumers of the module being refactored; define "behavior baseline" — the set of tests that must still pass after refactor; flag risk areas (shared state, async flows, external integrations)
+- **Output:** `docs/<refactor>/refactor_plan.md` — scope, boundaries, baseline test list, risk notes
+- **Done when:** `@team-lead` approves plan; boundaries are unambiguous
+
+### 2. Baseline Test Coverage — `@qa` + `@developer`
+- **Input:** refactor plan + current codebase
+- **Actions:** ensure all critical flows in scope are covered by automated tests before any changes; add missing tests if coverage gaps exist — this is the safety net; document the baseline coverage metrics
+- **Output:** baseline test suite passing; coverage metrics recorded
+- **Done when:** critical flows are covered; `make test` green on current code
+
+### 3. Incremental Refactor Implementation — `@developer`
+- **Input:** approved plan + baseline tests
+- **Actions:**
+  - refactor in small, reviewable increments — one conceptual change per commit
+  - run `make test` after each commit — if tests break, revert immediately
+  - do not change behavior while refactoring — behavior changes require a separate PR
+  - use strangler fig or parallel implementation pattern for high-risk module replacements
+- **Output:** refactored module on feature branch; all baseline tests passing
+- **Done when:** all planned scope refactored; baseline tests still green; no behavior changes introduced
+
+### 4. Regression Validation — `@qa`
+- **Input:** refactored branch
+- **Actions:** run full regression suite; perform exploratory testing on affected flows; compare observable behavior (API responses, DB state, logs) against baseline; verify performance is not degraded (run EXPLAIN ANALYZE on key queries if DB touched)
+- **Output:** `behavior_parity_evidence.md` — test results, behavior comparison, performance check
+- **Done when:** no regressions detected; behavior parity confirmed
+
+### 5. Review / Fix Loop — `@team-lead` + `@developer` + `@qa`
+- **Input:** refactored branch + parity evidence
+- **Actions:** `@team-lead` reviews structural improvements against plan goals; flags any remaining issues; `@developer` fixes; `@qa` re-verifies
+- **Output:** approved refactor
+- **Done when:** `@team-lead` confirms improvement is achieved; no open issues
+
+### 6. Closure with Parity Report — `@team-lead`
+- **Input:** approved refactor
+- **Actions:** confirm that the refactor achieved its stated goal (reduced complexity, improved layering, etc.); sign off with a brief note on what was improved
+- **Output:** merge approval + note in `refactor_plan.md`: "Goal achieved: <description>"
+- **Done when:** PR merged
+
+## Exit
+Merged refactor + behavior parity confirmed + improvement goal achieved = refactor complete.