Readiness:
{[{
score: 1,
label: "Not Ready"
}, {
score: 2,
label: "Significant Prep"
}, {
score: 3,
label: "Moderate Prep"
}, {
score: 4,
label: "Minor Prep"
}, {
score: 5,
label: "Ready"
}].map(({score, label}) => {
const c = scoreColor(score);
return
;
})}
;
}
function strategyDistribution() {
const counts = {};
Object.values(SAMPLE_DATA).forEach(d => {
counts[d.strategy] = (counts[d.strategy] || 0) + 1;
});
const total = Object.values(counts).reduce((a, b) => a + b, 0);
return
Modernization Readiness Heatmap
Component-level readiness scores across assessment domains · Click any row for details
{legendBlock()}
{strategyDistribution()}
|
Component
|
{DOMAINS.map(d =>
{d.label}
| )}
Overall
|
Strategy
|
{COMPONENTS.map(comp => {
const d = SAMPLE_DATA[comp];
const isSelected = selected === comp;
return setSelected(isSelected ? null : comp)} style={{
cursor: "pointer",
backgroundColor: isSelected ? "#1a1a2e" : "transparent",
transition: "background-color 0.15s ease"
}}>
|
{comp}
|
{DOMAINS.map(domain => {
const c = scoreColor(d[domain.key]);
return setSelected(isSelected ? null : comp)} style={{
backgroundColor: c.bg,
color: c.text,
border: isSelected ? `2px solid ${c.border}` : "1px solid #333",
padding: "8px 12px",
textAlign: "center",
cursor: "pointer",
fontWeight: 600,
fontSize: "14px",
transition: "all 0.15s ease",
minWidth: "44px"
}}>
{d[domain.key]}
| ;
})}
{scoreCell({
score: d.overall,
isSelected,
onClick: () => setSelected(isSelected ? null : comp)
})}
{strategyBadge({
strategy: d.strategy
})}
|
;
})}
{detail &&
{selected}
{strategyBadge({
strategy: detail.strategy
})}
Effort: {detail.effort}
KEY BLOCKERS
{detail.blockers}
}
Sample data — replace with actual assessment scores from Step 5 of the Codebase Assessment playbook
;
};
## Overview
Every modernization program starts with the same question: what exactly are we dealing with?
The answer is almost never what people expect. Engineering teams who've worked on a system for years consistently discover architectural connections, dead code paths, and undocumented dependencies during a formal assessment. Tribal knowledge covers the 20% of the system that changes regularly. The other 80% — the batch jobs that run once a month, the integration points nobody remembers building, the utility modules that seven services quietly depend on — hide until you look systematically.
Traditional assessment approaches rely on manual code sampling and architect interviews, producing a snapshot of what people *think* the system looks like. CoreStory changes this by ingesting and semantically understanding the entire codebase, giving your assessment team an **Expert** that can answer specific architectural questions against the full system — not a sample, not a summary, the actual code.
This playbook provides a structured methodology for evaluating a codebase's modernization readiness across seven domains: architectural complexity, dependency chains, technical debt, security and compliance, testability, data architecture, and — critically for mainframe systems — non-code artifacts that encode business logic never captured in application code.
**Who this is for:** Architects, engineering leads, and modernization teams performing the first phase of a modernization initiative. Also useful for consultants and system integrators scoping modernization engagements.
**What you'll get:** A Modernization Readiness Report with an architecture map, dependency graph, tech debt inventory, risk register, and component-level readiness scores with a recommended modernization strategy per component.
**Relationship to M\&A Due Diligence:** This playbook shares methodology DNA with the [M\&A Technical Due Diligence](/playbooks/ma-technical-due-diligence) playbook — both systematically interrogate a codebase across risk domains. The difference is the lens. M\&A evaluates a codebase you *don't* own for acquisition risk. Codebase Assessment evaluates a codebase you *do* own for transformation readiness. The interrogation categories differ accordingly: M\&A focuses on deal-affecting risks (licensing, secrets, PII exposure); Codebase Assessment focuses on transformation-readiness factors (coupling, decomposability, testability, data architecture).
***
## When to Use This Playbook
* You're planning a modernization initiative and need a rigorous baseline of the current system's architecture, dependencies, and technical debt
* You need to determine *which* modernization strategy (the 7 Rs) applies to each component — not a single system-wide strategy
* You're evaluating whether a legacy system is ready for modernization at all, or whether prerequisites (test coverage, documentation, domain expertise) must be addressed first
* You need evidence-based scope and effort estimates for a modernization proposal
* You're inheriting a legacy system from another team and need architectural orientation before making changes
## When to Skip This Playbook
* You already have a recent, thorough architectural assessment and need to move directly to strategy selection — start at [Target Architecture](/playbooks/modernization/target-architecture)
* You're evaluating a codebase for acquisition rather than internal modernization — use [M\&A Technical Due Diligence](/playbooks/ma-technical-due-diligence) instead
* The system is trivially small (under \~10k LOC) and its architecture is self-evident — you can proceed directly to refactoring
* You've already decided on a full rebuild with no legacy component reuse — the assessment adds less value when nothing will be retained
***
## Prerequisites
* A **CoreStory account** with the legacy codebase ingested and ingestion complete
* An **AI coding agent** with CoreStory MCP configured (see [Supercharging AI Agents](/getting-started/supercharging-ai-agents) for setup)
* **Repository access** for the legacy codebase (for the agent to cross-reference CoreStory findings against source)
* (Recommended) Access to **architecture documentation**, if it exists — even outdated docs help frame questions
* (Recommended) **Domain experts** who can validate architectural findings — especially for mainframe systems where business logic hides in non-code artifacts (JCL, copybooks, CICS configuration, VSAM data stores)
***
## How It Works
### CoreStory MCP Tools Used
This playbook uses the following tools from the CoreStory MCP server:
| Tool | Step(s) | Purpose |
| ---------------------- | ------------- | ------------------------------------------------------------- |
| `list_projects` | 1 | Find the target project |
| `create_conversation` | 1 | Start a dedicated assessment conversation thread |
| `send_message` | 2, 3, 4, 5, 6 | Query CoreStory for architecture analysis and risk assessment |
| `get_project_prd` | 1 | Retrieve synthesized PRD for business context |
| `get_project_techspec` | 1 | Retrieve synthesized TechSpec for architecture analysis |
| `list_conversations` | Any | Review existing conversation threads |
| `get_conversation` | Any | Retrieve conversation history for report synthesis |
| `rename_conversation` | 6 | Mark completed thread with "RESOLVED" prefix |
**A note on the PRD and TechSpec:** These documents are often very large — too large for an agent to hold in a single context window. Rather than reading them end-to-end, query CoreStory about their contents via `send_message`. CoreStory has already ingested these documents and can answer targeted questions about them efficiently.
### The Assessment Workflow
> **Note:** The steps below are internal to this playbook. They are sub-steps of Phase 1 in the [six-phase modernization framework](/playbooks/code-modernization), not a separate numbering system.
Codebase assessment with CoreStory follows a six-step pattern:
1. **Setup & Orientation** — Confirm the target project, review synthesized specs for architectural context, and create a named conversation thread for the assessment.
2. **Architecture Mapping** — Map major components, services, data stores, and communication patterns. Establish the structural vocabulary that all subsequent steps reference.
3. **Dependency Analysis** — Identify internal coupling, external dependencies, shared data stores, and integration points. This step reveals what *can* be decomposed and what *must* move together.
4. **Tech Debt & Risk Assessment** — Catalog technical debt, security risks, compliance gaps, and code quality issues. Each finding includes severity and blast radius.
5. **Modernization Readiness Scoring** — Score each component on modernization readiness. Recommend a modernization strategy (from the 7 Rs) per component, not one strategy for the whole system.
6. **Report Generation** — Synthesize findings into the Modernization Readiness Report. This is the deliverable that feeds Phase 3 (Target Architecture) of the broader modernization workflow.
### Expert Before Navigator
Before searching for specific issues or code paths, first use CoreStory to understand how the system is *designed* to work — its intended architecture, data flow patterns, and integration model. This architectural baseline makes it far easier to spot deviations, shortcuts, coupling hotspots, and technical debt. Ask "what is this system?" before asking "what's wrong with this system?"
```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#1a1a2e', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#c9a84c', 'lineColor': '#c9a84c', 'secondaryColor': '#16213e', 'tertiaryColor': '#0f3460', 'fontFamily': 'Inter, system-ui, sans-serif'}}}%%
graph TD
subgraph foundation["🧭 Expert Before Navigator — Understand architecture from specs before searching for issues"]
direction LR
F1[" "]
end
P1["