acardozzo/rx-plan

Prerequisites

None (uses git for worktrees)

Check all dependencies: bash scripts/rx-deps.sh or bash scripts/rx-deps.sh --install

rx-plan -- Versioned Improvement Plan Generator

Reads rx report results and generates actionable, versioned improvement plans for every dimension scoring below A+ (97). Each plan is traceable to a specific report, ordered by impact, and includes measurable acceptance criteria.

Announce at start: "I'm using rx-plan to generate improvement plans from the {domain} report. Creating plans for dimensions below A+ (97)."

Inputs

Accepts one of:

• A domain name (e.g., arch-rx, sec-rx, code-rx) to read the latest report for that domain
• A report file path (e.g., docs/audits/2026-03-15-arch-rx-all.md) to use a specific report
• No argument -- uses the most recent rx report from conversation context or docs/audits/

/rx-plan arch-rx
/rx-plan docs/audits/2026-03-15-sec-rx-report.md
/rx-plan

Process Overview

1. Locate the rx report -- Find the most recent report for the given domain
2. Parse scores -- Extract dimension scores, sub-metric scores, and existing recommendations
3. Filter dimensions -- Identify all dimensions scoring below 97 (not yet A+)
4. Check existing plans -- Look in docs/rx-plans/{domain}/{dimension}/ for previous versions
5. Generate plans -- Create one plan per below-A+ dimension, versioned correctly
6. Save report snapshot -- Copy the rx report as v{N}-{date}-report.md alongside the plan
7. Update summary -- Refresh docs/rx-plans/{domain}/summary.md with current progress
8. Update dashboard -- Refresh docs/rx-plans/dashboard.md with global state

Step 1: Locate the Report

Search for the report in this order:

1. If a file path is given, read it directly
2. If a domain name is given, find the most recent file matching docs/audits/*-{domain}-*.md
3. If no argument, check conversation context for the last rx report output
4. If still nothing, list docs/audits/ sorted by date descending and pick the newest

Extract from the report:

• Domain name (e.g., arch-rx)
• Overall score and grade
• Per-dimension scores and grades
• Per-sub-metric scores
• Existing ADR recommendations or improvement suggestions

Step 2: Determine Versions

For each dimension scoring below 97:

1. Check if docs/rx-plans/{domain}/{dimension-slug}/ exists
2. If it exists, find the highest version number v{N} from existing plan filenames
3. New version = v{N+1}
4. If no previous plans exist, new version = v1

Dimension slug convention: lowercase, dash-separated, prefixed with dimension number. Examples: d01-communication, d02-async-event, d03-resilience

Step 3: Generate Plan Files

For each below-A+ dimension, create docs/rx-plans/{domain}/{dimension-slug}/v{N}-{date}-plan.md:

# Improvement Plan: {Domain} / {Dimension}

**Version**: v{N}
**Date**: {YYYY-MM-DD}
**Domain**: {rx skill name} (e.g., arch-rx)
**Dimension**: {dimension name} (e.g., D2: Async & Event Architecture)
**Current Score**: {score} ({grade})
**Target Score**: 97+ (A+)
**Gap**: {delta} points

## Previous Versions
| Version | Date | Score | Delta | Status |
|---------|------|-------|-------|--------|
| v1 | 2026-03-15 | 40 (F) | -- | Completed |
| v2 | 2026-03-20 | 72 (C-) | +32 | Completed |
| v{N} (this) | {date} | {score} ({grade}) | {delta from prev} | Planning |

> If this is v1, the table has only one row with Delta = "--".

## Gap Analysis

| Sub-Metric | Current | Target | Gap | Key Blocker |
|------------|---------|--------|-----|-------------|
| M{X}.1 {name} | {score} | 97+ | {delta} | {specific blocker} |
| M{X}.2 {name} | {score} | 97+ | {delta} | {specific blocker} |
| M{X}.3 {name} | {score} | 97+ | {delta} | {specific blocker} |
| M{X}.4 {name} | {score} | 97+ | {delta} | {specific blocker} |

## Steps (ordered by impact)

### Step 1: {Action} -> +{N} points on M{X}.{Y}
- **What**: {Concrete action -- what exactly to implement or change}
- **Where**: {File paths -- specific files/directories to modify}
- **Why**: {Framework reference -- POSA/EIP/WCAG/OWASP/12-Factor/etc.}
- **How**:

{Code example, command, or configuration snippet}

- **Acceptance Criteria**:
- [ ] {Measurable criterion 1}
- [ ] {Measurable criterion 2}
- **Effort**: {S/M/L}
- **Depends on**: {Step N or "none"}

### Step 2: {Action} -> +{N} points on M{X}.{Y}
...

> Steps are ordered by point impact descending. If two steps have equal impact,
> order by effort ascending (quick wins first). Include ALL steps needed to reach 97+.

## After Completing This Plan
- Run `/{domain}` to re-evaluate this dimension
- Expected new score: {projected score based on step impacts}
- If score >= 97: dimension is A+, archive this plan
- If score < 97: auto-generate v{N+1} plan with remaining gaps
- Related rx skills to run: {list of complementary rx skills}

## Notes
{Any context from the rx report that's relevant -- detected stack, N/A dimensions,
dependencies on other dimensions, external constraints, etc.}

Step 4: Save Report Snapshot

Copy (or extract) the relevant rx report data to: docs/rx-plans/{domain}/{dimension-slug}/v{N}-{date}-report.md

This file contains the full rx report (or the relevant dimension section) that generated the plan. This creates an immutable audit trail: every plan version links to the exact report that prompted it.

Step 5: Update Summary

Create or update docs/rx-plans/{domain}/summary.md:

# {Domain} Progress Tracker

**Last evaluated**: {date}
**Overall score**: {score} ({grade})

| Dimension | Current | Target | Plans | Latest | Status |
|-----------|---------|--------|-------|--------|--------|
| D1 {name} | {score} ({grade}) | 97 (A+) | v{N} | {date} | {In Progress/Planning/Complete} |
| D2 {name} | {score} ({grade}) | 97 (A+) | v{N} | {date} | {status} |
| ... | ... | ... | ... | ... | ... |

> Dimensions at 97+ show Status = "Complete" with no plan version needed.

## Timeline
| Date | Event | Score Change |
|------|-------|-------------|
| {date} | Initial rx report | {score} ({grade}) |
| {date} | v1 plans completed | {score} ({grade}) {+/-delta} |
| ... | ... | ... |

Step 6: Update Dashboard

Create or update docs/rx-plans/dashboard.md:

# rx-suite Dashboard

**Last updated**: {date}

## Overall Progress
| Domain | Score | Grade | Dimensions at A+ | Total | Progress |
|--------|-------|-------|-------------------|-------|----------|
| arch-rx | {score} | {grade} | {count}/{total} | {total} | {progress bar} |
| sec-rx | {score} | {grade} | {count}/{total} | {total} | {progress bar} |
| code-rx | {score} | {grade} | {count}/{total} | {total} | {progress bar} |
| ... | ... | ... | ... | ... | ... |

> Progress bar: use filled/empty blocks proportional to A+ percentage.
> Example: 3/11 = 27% -> block chars approximating that percentage

## Active Plans
| Domain | Dimension | Version | Status | Next Action |
|--------|-----------|---------|--------|-------------|
| {domain} | {dimension} | v{N} | {In Progress/Planning} | {Step 1 action summary} |
| ... | ... | ... | ... | ... |

## Completed Dimensions (A+)
| Domain | Dimension | Achieved | Date |
|--------|-----------|----------|------|
| {domain} | {dimension} | {score} (A+) | {date} |
| ... | ... | ... | ... |

## Recommendations
- **Next rx to run**: {domain with stalest report or most active plans}
- **Highest-impact plan**: {domain/dimension with largest gap and smallest effort}
- **Quick wins**: {plans with S effort and significant point gains}

Progress bar rendering:

• Calculate percentage: (dimensions_at_aplus / total_dimensions) * 100
• Use 10 block characters total
• Filled blocks = round(percentage / 10)
• Empty blocks = 10 - filled blocks
• Format: {filled}{empty} {percentage}%

Rules

1. Plans are always versioned -- never overwrite. Each new plan for the same dimension gets an incremented version number (v1, v2, v3...). Previous versions remain untouched as an audit trail.

2. Each plan traces to a specific rx report. The report snapshot (v{N}-{date}-report.md) is saved alongside the plan. This creates full traceability from plan to evidence.

3. Steps are ordered by point impact. The step that yields the most score improvement comes first. If two steps have equal impact, the one with less effort comes first (quick wins).

4. Acceptance criteria must be measurable. Every step's acceptance criteria must be verifiable by re-running the rx skill or by checking a concrete artifact (file exists, test passes, config value is set). No subjective criteria like "code is cleaner".

5. After completing a plan, re-run the rx skill to verify. The plan explicitly states which rx skill to run. The new report feeds into the next plan version if gaps remain.

6. Auto-increment version when re-planning. When rx-plan runs against a dimension that already has plans, it reads the previous version's score, computes the delta, and generates v{N+1} with updated gap analysis.

7. Dashboard is always updated. Every invocation of rx-plan must update both the domain summary and the global dashboard. These files are the single source of truth for progress tracking.

8. One plan per dimension. Never combine multiple dimensions into a single plan file. Each dimension gets its own directory and its own plan versions.

9. Preserve previous version history. When generating a new plan, the "Previous Versions" table includes ALL prior versions with their scores and deltas, not just the immediately preceding one.

10. Score 97+ means complete. Dimensions scoring 97 or above are considered A+ and do not get plans. They appear in the dashboard's "Completed Dimensions" table.

11. Gap analysis is per-sub-metric. The gap analysis table breaks down the dimension score into its constituent sub-metrics, showing exactly where points are lost.

12. Steps include file paths. Every step must reference specific files or directories in the project. Generic advice like "add error handling" is not acceptable without pointing to where.

13. Framework references are mandatory. Every step must cite the framework, standard, or pattern that justifies the recommendation (POSA, EIP, OWASP, 12-Factor, CNCF, etc.).

14. Effort estimates use S/M/L. Small = less than 2 hours, Medium = 2-8 hours, Large = more than 8 hours. These are rough guides for prioritization.

15. Dependencies between steps are explicit. If Step 3 requires Step 1 to be done first, the dependency is stated. This prevents wasted effort from out-of-order execution.

16. Report snapshots are dimension-scoped. The saved report snapshot includes the full report context but highlights the specific dimension being planned. If the full report is very large, extract just the relevant dimension section plus the overall scorecard.

17. N/A dimensions are skipped. If a dimension is scored N/A (100 by convention) in the rx report, no plan is generated for it.

18. Cross-domain dependencies are noted. If an improvement in one domain (e.g., arch-rx D9 Security) would also improve another domain (e.g., sec-rx D1 Injection), note this in the plan's Notes section.

19. Projected scores are conservative. When estimating the score after completing a plan, use the lower bound of the expected improvement range. Overpromising undermines trust in the planning system.