---
title: "Agent Skill to Modernize Brief"
platform: "Promptally"
canonical_url: "https://app.promptally.dev/p/skill-modernize-brief"
modality: "SKILL"
category: "Fullstack & Backend Engineering"
compatible_models: [Universal / Model Agnostic]
access_tier: "Free Public Artifact (No Auth Required)"
license: "MIT"
---

# Agent Skill to Modernize Brief

**Summary:** Agent Skill to Modernize Brief is a verified SKILL blueprint on Promptally in Fullstack & Backend Engineering optimized for leading AI models. write to file the phased Modernization Brief — the plan a steering committee approves and the build commands execute against. Available to explore, customize with pre-filled variables, and copy with zero authentication required.

## Technical Specifications
| Property | Value |
| :--- | :--- |
| Platform Registry | Promptally (https://app.promptally.dev) |
| Modality | SKILL |
| Category | Fullstack & Backend Engineering |
| Compatible Engines | Universal / Model Agnostic |
| Dynamic Variables | None (Static Blueprint) |
| Approx. Token Length | 2,187 |
| Access Tier | Free Public Artifact (No Auth Required) |
| License | MIT |

### Pre-Filled Template & Production Source

````md
---
name: modernize-brief
description: write_to_file the phased Modernization Brief — the plan a steering committee approves and the build commands execute against
---

Synthesize everything in `analysis/$system/` into a **Modernization Brief**: the single
document a steering committee approves and engineering executes. Target stack:
`$target_stack` (if blank, the one in `analysis/$system/INTENT.md`, else recommend one from the assessment).

view_file `ASSESSMENT.md`, `topology.json` (and the `.mmd` files beside it; never read
`TOPOLOGY.html`, it is a viewer with the data minified inside) in `analysis/$system/` first,
and `BUSINESS_RULES.md` too unless this is a same-technology **uplift** (the intent or the assessment
says so): an uplift keeps the code, so its Behavior Contract is the recorded baseline and `extract-rules`
can wait. If a required file is missing, say so and stop: they come from `assess`, `map` and
`extract-rules`, which run first. Four more inputs are conditional:

- **`RULE_REVIEWS.json` / `RULE_REVIEWS.md`**, if they exist (written by `/code-modernization:modernize-review`):
  a person's verdicts on individual rules. Never put a rule marked `wrong` or `discuss` in the Behavior
  Contract as settled behavior: list each in section 7 as an open question with the reviewer's note, and
  block the phase that covers its module on it. A `confirmed` rule counts as confirmed by a person.
- **`INTENT.md`**, if it exists (written by `/code-modernization:modernize`): what the person wants (goal, target,
  what must stay true). It is the objective of this plan; never override it with a guess. Its goal decides each
  phase's build command: a newer version of the same technology means `uplift`, a rewrite in another technology
  means `transform`, a rebuild on a new architecture means `reimagine`. Without it, the assessment's pattern decides.
- **`PREFLIGHT.md`**, if it exists. It holds two things nothing else has: the human's answers
  to preflight Check 0 (scope, local build and test, bespoke build infrastructure, prior
  attempts, what is off limits) and the Check 6 **scope boundary** (whether the source is a
  slice of a larger codebase, and what outside it depends on code inside it). Both constrain
  this plan more than anything derivable from the source. Never override a human's answer with
  a guess.
- **`DELTA_CATALOG.md`**, **required** when the target is a newer version of the *same* stack.
  An uplift's phase order is decided by its version deltas, above all by whether the existing
  tests can even run on the target runtime; phasing without the catalog is planning blind. If it
  is missing, produce it first (`/code-modernization:modernize-uplift $system <source> $target_stack`
  through its delta-catalog step, or the **version-delta-analyst** agent) and **wait for its result**:
  never end your turn while an agent is still running, and never write the brief before the catalog
  exists. Do not guess at deltas.

**Staleness.** If an input is newer than an existing `MODERNIZATION_BRIEF.md`, regenerating is
justified. If the brief is newer than every input and the user re-ran this anyway, ask what
changed. Note the input timestamps in the brief's header.

## The Brief

write_to_file `analysis/$system/MODERNIZATION_BRIEF.md` with these sections.

**1. Objective.** One paragraph: from what, to what, why now.

**2. Target Architecture.** A Mermaid C4 Container diagram of the end state naming every service,
data store and integration, then a table mapping each legacy component to its target component(s).

**3. Phased Sequence.** 3–6 phases, ordered by **strangler fig** for a cross-stack rewrite
(lowest risk and fewest dependencies first) or **build-graph leaf-first** for an uplift
(libraries before the apps that use them). For an uplift, three overrides decide whether the
plan works; the uplift command re-applies them at execution, and the two must never disagree:

1. **The test harness is a prerequisite, not a leaf.** If the catalog shows the test framework or
   runner does not support the target (NUnit 2 or MSTest v1 on modern .NET, JUnit 4 without the
   vintage engine, `nose` on Python 3), migrating it is **Phase 1 by itself**.
2. **A dependency delta every consumer shares forces a coordinated cut** (an ORM major version,
   `javax` to `jakarta`): it gets its own cross-cutting phase, not an incremental leaf-first one.
3. **A shared node with consumers outside the scope** (from the preflight boundary check) needs an
   explicit decision in the phase that touches it: keep it buildable for old and new consumers
   (multi-targeting, publishing both), widen the scope to include the consumers, or schedule the
   break. Never silently migrate it in place.

write_to_file every phase in this exact shape, because the build commands and the progress pane read it:

```
#### Phase N — <name>
Command: /code-modernization:modernize-transform | -uplift | -reimagine      (exactly one)
Modules: <module ids exactly as in topology.json, comma separated>
Scale: S | M | L | XL
Risk: <level>; <top 2 risks and mitigations>
Entry criteria:
- [ ] <a condition that can be checked>
Exit criteria:
- [ ] <a condition that can be checked>
```

- `transform` is a cross-stack module rewrite, `reimagine` a greenfield rebuild, and `uplift` a
  same-stack version bump (when the target is a newer version of the same stack, it is the path, not
  `transform`).
- **Scale** is a T-shirt size anchored to the phase's share of the assessment's complexity index. It
  ranks phases against each other and is **not** a duration: state no person-months, weeks, dates or
  delivery estimate (agentic work does not follow human-team productivity).
- **Criteria are conditions, never states.** "All P0 rules in Phase 1 proven equivalent" is a
  criterion; "P0 rules proven" is a claim. Make entry criteria *checkable preconditions* ("baseline
  recorded in `analysis/$system/BASELINE.md`", "pilot playbook approved"). The build commands read the
  brief and treat them as binding, and they may tick a box or add a note but never reword a criterion:
  a proposed change goes on a `Proposed revision:` line for the approver. Tell the approver they steer
  execution by editing this file: an edited criterion is honored, a chat message is not.
- Draw the phases as a Mermaid `flowchart LR` of **sequence and dependencies**, never a `gantt`
  (that encodes durations this plan deliberately does not claim).
- **Phase 1 is a pilot, and this brief is a hypothesis.** When a phase's units share one recipe (an
  uplift over many projects, a transform over many similar modules), name one representative unit as
  its first slice in the entry criteria. Say in §3 that what the pilot surfaces (a delta the analysis
  missed, a prerequisite that reorders the phases, an environment fact nobody wrote down) is *expected*
  to revise the brief, and that regenerating it after the pilot is the normal path. Legacy systems hide
  their surprises in the build and the runtime, not the source.

**4. Business Walkthroughs.** For each persona flow in `topology.json` (`flows`), a short table:
persona, what happens in business language, which legacy modules implement it, and which phase
replaces each. This is the section non-technical approvers read. With no flows, derive 2–3 from the
entry points and mark them as needing SME confirmation.

**5. Behavior Contract.** The **P0 rules** from `BUSINESS_RULES.md` (the ones the system's core purpose
depends on, or that are costly if wrong) that MUST be proven equivalent before any phase ships: they become the regression suite.
Flag any P0 rule below High confidence as a blocker needing SME confirmation before its phase starts. For an uplift
with no rules file, the contract is the baseline: `analysis/$system/BASELINE.md` and the result files it points to,
which the new version must reproduce.

**6. Validation Strategy.** Which combination applies, per phase: characterization tests, contract
tests, dual-execution diff, property-based tests, manual UAT.

**7. Open Questions.** Everything needing a human decision before Phase 1, each a checkbox the
approver ticks.

**8. Approval Block**

```
Approved by: ________________  Date: __________
Approval covers: Phase 1 only | Full plan
```

## Finish

Refresh the report: `python3 "${ANTIGRAVITY_PLUGIN_ROOT}/scripts/build_report.py" $system` (a convenience: if it fails or `python3` is missing, say so in one line and carry on). Present a summary of the brief and **stop: write nothing further until the user
explicitly approves** (use plan mode if the session supports it). This is the human control point, and
"no objection" is not approval. After approval, the next step is Phase 1's command.

````

## Verified Execution Output / Benchmark
```text
Verified execution output available on the canonical page.
```

## Related Blueprints on Promptally
- [Agent Skill to Knowledge Ops](https://app.promptally.dev/p/skill-knowledge-ops)
- [Agent Skill to Content Hash Cache Pattern](https://app.promptally.dev/p/skill-content-hash-cache-pattern)
- [Agent Skill to Ck](https://app.promptally.dev/p/skill-ck)
- [Agent Skill to Swift Protocol Di Testing](https://app.promptally.dev/p/skill-swift-protocol-di-testing)
- [Agent Skill to Prisma Patterns](https://app.promptally.dev/p/skill-prisma-patterns)
- [Agent Skill to Agentic Engineering](https://app.promptally.dev/p/skill-agentic-engineering)
- [Agent Skill to Python Patterns](https://app.promptally.dev/p/skill-python-patterns)
- [Agent Skill to Docs Governance](https://app.promptally.dev/p/skill-docs-governance)