From e5939029ecdda7e9b8d30854e95eed2a5ff60062 Mon Sep 17 00:00:00 2001 From: Morgan Westlee Lunt Date: Tue, 9 Jun 2026 21:21:50 +0000 Subject: [PATCH] code-modernization: COCOMO is a complexity index, never a modernization timeline COCOMO's constants encode human-team productivity; presenting its person-months as how long an agentic modernization will take (or cost) is a claim we should not make. Reframe COCOMO everywhere as a RELATIVE complexity/scale index for ranking and sequencing systems only: - assess: capture COCOMO as a complexity index; explicitly ignore scc's 'Estimated Schedule Effort' and cost-in-dollars; ASSESSMENT 'Effort Estimation' section becomes 'Relative Scale' with a not-a-timeline note; portfolio heat-map column renamed Complexity (COCOMO index). - brief: phase plan uses relative T-shirt sizing, not person-months/weeks; phases render as a dependency flowchart, not a gantt (gantt = calendar). - portfolio-assess.js: field cocomoPm -> complexityIndex; return label carries the not-a-duration caveat. - README: 'A note on COCOMO' explains the index framing and points at better intrinsic-complexity proxies. Co-Authored-By: Claude Fable 5 --- plugins/code-modernization/README.md | 6 ++-- .../commands/modernize-assess.md | 32 +++++++++++++------ .../commands/modernize-brief.md | 13 ++++++-- .../commands/modernize-preflight.md | 2 +- .../workflows/portfolio-assess.js | 13 +++++--- 5 files changed, 46 insertions(+), 20 deletions(-) diff --git a/plugins/code-modernization/README.md b/plugins/code-modernization/README.md index 1446299..2e11355 100644 --- a/plugins/code-modernization/README.md +++ b/plugins/code-modernization/README.md @@ -40,7 +40,7 @@ to direct subagent fan-out on older builds — no configuration needed. |---|---| | `/modernize-extract-rules` | Extraction loops until two consecutive rounds find nothing new; every rule's `file:line` citation is verified by an independent referee before entering the catalog; P0 rules face a two-judge panel before they can anchor the behavior contract. | | `/modernize-harden` | Five class-scoped finders in parallel; every finding is adversarially refuted (Critical/High double-judged), so false positives die before `SECURITY_FINDINGS.md`. | -| `/modernize-assess --portfolio` | One survey agent per system, pipelined independently; COCOMO computed uniformly in code; crashed sweeps resume from cache. | +| `/modernize-assess --portfolio` | One survey agent per system, pipelined independently; the COCOMO complexity index computed uniformly in code; crashed sweeps resume from cache. | | `/modernize-reimagine` (Phase E) | The 3-service scaffolding cap is lifted — the runtime queues one agent per approved service. | These fan out more agents than the fallback path (tens, on a large estate) — @@ -86,7 +86,9 @@ The commands are designed to be run in order, but each produces a standalone art Environment readiness check, meant to run first: detects the legacy stack, checks analysis tooling, **smoke-compiles a real source file** with the legacy toolchain (the errors this surfaces — missing copybooks, wrong dialect flags — are the ones that otherwise appear mid-transform), inventories missing includes / deployment descriptors / binary-only artifacts, and probes for telemetry. Produces `analysis//PREFLIGHT.md` with a per-command Ready / Ready-with-gaps / Not-ready verdict. ### `/modernize-assess ` — or — `/modernize-assess --portfolio ` -Inventory the legacy codebase: languages, line counts, complexity, build system, integrations, technical debt, security posture, documentation gaps, and a COCOMO-derived effort estimate. Produces `analysis//ASSESSMENT.md` and `analysis//ARCHITECTURE.mmd`. Spawns `legacy-analyst` (×2) and `security-auditor` in parallel for deep reads. With `--portfolio`, sweeps every subdirectory of a parent directory and writes a sequencing heat-map to `analysis/portfolio.html`. +Inventory the legacy codebase: languages, line counts, complexity, build system, integrations, technical debt, security posture, documentation gaps, and a COCOMO-derived **relative complexity index** (a size/scale signal for ranking systems — explicitly *not* a modernization timeline or cost; see "A note on COCOMO" below). Produces `analysis//ASSESSMENT.md` and `analysis//ARCHITECTURE.mmd`. Spawns `legacy-analyst` (×2) and `security-auditor` in parallel for deep reads. With `--portfolio`, sweeps every subdirectory of a parent directory and writes a sequencing heat-map to `analysis/portfolio.html`. + +> **A note on COCOMO.** Both `assess` modes derive a COCOMO-II figure from code size. This plugin uses it **only as a relative complexity/scale index** — to rank and sequence systems and to size the legacy estate. It is deliberately **not** presented as a modernization timeline or cost, and the commands are instructed never to convert it to person-months, weeks, dates, or dollars. COCOMO's constants encode historical human-team productivity; agentic transformation does not follow those curves, so any duration derived from it would be wrong. If you have a better intrinsic-complexity proxy (cyclomatic-complexity density, coupling/fan-out, the topology's edge density, or the count of extracted P0 business rules), prefer it — COCOMO is the portable default, not the ceiling. ### `/modernize-map ` diff --git a/plugins/code-modernization/commands/modernize-assess.md b/plugins/code-modernization/commands/modernize-assess.md index 51c7346..a78f761 100644 --- a/plugins/code-modernization/commands/modernize-assess.md +++ b/plugins/code-modernization/commands/modernize-assess.md @@ -1,5 +1,5 @@ --- -description: Full discovery & portfolio analysis of a legacy system — inventory, complexity, debt, effort estimation +description: Full discovery & portfolio analysis of a legacy system — inventory, complexity, debt, relative scale argument-hint: [--show-secrets] | --portfolio --- @@ -62,11 +62,19 @@ cyclomatic complexity (CCN). For dependency freshness, locate the manifest (`package.json`, `pom.xml`, `*.csproj`, `requirements*.txt`, copybook dir) and note its age / pinned-version count. -## Step P2 — COCOMO-II effort +## Step P2 — COCOMO-II complexity index -Compute person-months per system using COCOMO-II basic: -`PM = 2.94 × (KSLOC)^1.10` (nominal scale factors). Show the formula and -inputs so the figure is defensible, not a guess. +Compute the COCOMO-II basic figure per system: `2.94 × (KSLOC)^1.10` +(nominal scale factors). Show the formula and inputs so it is defensible, +not a guess. + +**Use this only as a relative complexity/scale index** for ranking and +sequencing systems — bigger number = bigger, more complex estate. **It is +not a modernization timeline or cost.** The COCOMO person-month figure +assumes traditional human-team productivity; agentic transformation does +not follow those productivity curves, so do not present it (or convert it) +as how long the work will take or what it will cost. Label the column as an +index, not "person-months", and never attach a date or duration to it. ## Step P3 — Documentation coverage @@ -79,7 +87,7 @@ Report coverage % and the top undocumented subsystems. Write `analysis/portfolio.html` (dark `#1e1e1e` bg, `#d4d4d4` text, `#cc785c` accent, system-ui font, all CSS inline). One row per system; columns: **System · Lang · KSLOC · Files · Mean CCN · Max CCN · Dep -Freshness · Doc Coverage % · COCOMO PM · Risk**. Color-grade the PM and +Freshness · Doc Coverage % · Complexity (COCOMO index) · Risk**. Color-grade the index and Risk cells (green→amber→red). Below the table, a 2-3 sentence sequencing recommendation: which system first and why. @@ -101,11 +109,15 @@ Run and show the output of: scc legacy/$1 ``` Then run `scc --by-file -s complexity legacy/$1 | head -25` to identify the -highest-complexity files. Capture the COCOMO effort/cost estimate scc provides. +highest-complexity files. Capture scc's COCOMO figure **only as a relative +complexity/scale index** — and **ignore scc's "Estimated Schedule Effort" +and cost-in-dollars lines**: those project a human-team timeline and budget, +which are invalid for agentic modernization (see the not-a-timeline note in +Step 6). If `scc` is not installed, fall back in order: -1. `cloc legacy/$1` for the LOC table, then compute COCOMO-II effort - yourself: `PM = 2.94 × (KSLOC)^1.10` (nominal scale factors). Show the +1. `cloc legacy/$1` for the LOC table, then compute the COCOMO-II index + yourself: `2.94 × (KSLOC)^1.10` (nominal scale factors). Show the inputs. 2. If `cloc` is also missing, use `find` + `wc -l` grouped by extension for LOC, and rank file complexity by counting decision keywords @@ -208,7 +220,7 @@ Create `analysis/$1/ASSESSMENT.md` with these sections: - **Technical Debt** (top 10, ranked) - **Security Findings** (CWE table) - **Documentation Gaps** (top 5) -- **Effort Estimation** (COCOMO-derived person-months, ±range, key cost drivers) +- **Relative Scale** (the COCOMO-II index + KSLOC as a complexity/scale signal for ranking this system against others. **Not a timeline:** state plainly that this is a relative size measure, not an estimate of how long modernization will take or what it will cost — it assumes traditional human-team productivity, which agentic transformation does not follow. Do not print person-months, a schedule, a cost, or a date.) - **Recommended Modernization Pattern** (one of: Rehost / Replatform / Refactor / Rearchitect / Rebuild / Replace — with one-paragraph rationale) Also create `analysis/$1/ARCHITECTURE.mmd` containing the Mermaid domain diff --git a/plugins/code-modernization/commands/modernize-brief.md b/plugins/code-modernization/commands/modernize-brief.md index 5daa611..9546733 100644 --- a/plugins/code-modernization/commands/modernize-brief.md +++ b/plugins/code-modernization/commands/modernize-brief.md @@ -40,11 +40,18 @@ fewest-dependencies first. For each phase: - Scope (which legacy modules, which target services) - Entry criteria (what must be true to start) - Exit criteria (what tests/metrics prove it's done) -- Estimated effort (person-months, same unit as the assessment's COCOMO - figure — convert deliberately if you present weeks) +- Relative scale (T-shirt size — S/M/L/XL — anchored to the phase's share + of the assessment's COCOMO complexity index. This ranks phases by size + against each other; it is **not** a duration. Do **not** state + person-months, weeks, calendar dates, or a delivery estimate — agentic + transformation does not follow the human-team productivity curves those + units assume, so any time figure here would be misleading.) - Risk level + top 2 risks + mitigation -Render the phases as a Mermaid `gantt` chart. +Render the phases as a Mermaid `flowchart LR` showing **sequence and +dependencies** (Phase 1 → Phase 2 → …, with branches where phases are +independent). Do **not** use a `gantt` chart — gantt encodes calendar +durations, and this plan deliberately makes no time claims. ### 4. Business Walkthroughs For each persona flow in `analysis/$1/topology.json` (`flows` — produced diff --git a/plugins/code-modernization/commands/modernize-preflight.md b/plugins/code-modernization/commands/modernize-preflight.md index ed283ea..ff91c2a 100644 --- a/plugins/code-modernization/commands/modernize-preflight.md +++ b/plugins/code-modernization/commands/modernize-preflight.md @@ -27,7 +27,7 @@ used for, and what degrades without it: | Tool | Used by | Without it | |---|---|---| -| `scc` (or `cloc`) | assess | LOC/complexity fall back to `find`+`wc`; COCOMO estimate gets coarser | +| `scc` (or `cloc`) | assess | LOC/complexity fall back to `find`+`wc`; the COCOMO complexity index gets coarser | | `lizard` | assess --portfolio | complexity estimated from decision-keyword counts | | `glow` | all | markdown artifacts render as plain text | | `delta` | transform | side-by-side diffs fall back to `diff -y` | diff --git a/plugins/code-modernization/workflows/portfolio-assess.js b/plugins/code-modernization/workflows/portfolio-assess.js index a794365..eb5f212 100644 --- a/plugins/code-modernization/workflows/portfolio-assess.js +++ b/plugins/code-modernization/workflows/portfolio-assess.js @@ -82,17 +82,22 @@ if (failed.length) { } // COCOMO-II basic, computed here so every row uses the identical formula: -// PM = 2.94 × (KSLOC)^1.10 (nominal scale factors). +// 2.94 × (KSLOC)^1.10 (nominal scale factors). This is a RELATIVE +// complexity/scale index for ranking systems — NOT a duration or cost. +// The calling command must render it as an index and never convert it to +// person-months / weeks / dates (agentic transformation breaks COCOMO's +// human-team productivity assumptions). for (const r of surveyed) { const ksloc = r.sloc / 1000 - r.cocomoPm = Math.round(2.94 * Math.pow(ksloc, 1.1) * 10) / 10 + r.complexityIndex = Math.round(2.94 * Math.pow(ksloc, 1.1) * 10) / 10 } -surveyed.sort((a, b) => b.cocomoPm - a.cocomoPm) +surveyed.sort((a, b) => b.complexityIndex - a.complexityIndex) return { parentDir, rows: surveyed, unmeasured: failed, - formula: 'PM = 2.94 × (KSLOC)^1.10 (COCOMO-II basic, nominal scale factors) — computed by the workflow, not estimated by agents', + complexityIndexFormula: + '2.94 × (KSLOC)^1.10 (COCOMO-II basic, nominal scale factors) — a RELATIVE complexity/scale index for ranking systems, computed by the workflow. NOT a duration or cost: do not render it as person-months/weeks/dates; agentic transformation does not follow COCOMO human-team productivity.', }