# Uw Plan

> Use after layer analysis is complete to interview the user about the rebuild strategy (target stack, what to keep vs rebuild, phasing, risk) and generate a data-grounded REBUILD-PLAN.md that records those decisions.

- **Type:** Skill
- **Install:** `agentstack add skill-nearform-unwind-uw-plan`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nearform](https://agentstack.voostack.com/s/nearform)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nearform](https://github.com/nearform)
- **Source:** https://github.com/nearform/unwind/tree/main/skills/uw-plan

## Install

```sh
agentstack add skill-nearform-unwind-uw-plan
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Synthesizing Findings → Rebuild Strategy

## Overview

Transform layer analysis into a **strategic rebuild plan** that answers HOW to
rebuild, not WHAT to rebuild. The plan is **co-authored with the user**, not guessed:
the strategic decisions that shape a rebuild — target stack, what to keep vs rebuild,
migration approach, phasing, risk tolerance — are ones only the user can make.

This skill **grills the user** the way the `grilling` skill does: walk the decision
tree one branch at a time, resolving dependencies in order, and **for every question
provide a recommended answer derived from the deterministic data**. If a question can
be answered from the scan/coverage data, **answer it from the data — don't ask**.

**Key Principle:** Layer docs are the source of truth for what exists. This plan
records the strategic *decisions* about re-use, phasing, and approach — grounded in the
deterministic brief — and references the layer docs for the detail.

**Requires:** `docs/unwind/layers/*/index.md` from layer specialists + verification reports
**Produces:**
- `docs/unwind/REBUILD-PLAN.md` — strategic rebuild approach, target stack, and a decisions log
- `docs/unwind/.cache/rebuild-decisions.json` — machine-readable record of the interview answers
- Updated `docs/unwind/architecture.md` if corrections needed after detailed analysis

## Prerequisites

Before using this skill:
1. All detected layers have been analyzed
2. Verification pass has completed (coverage reports exist under `.cache/coverage/`)
3. Layer folders exist in `docs/unwind/layers/` with index.md + section files

---

## Phase A — Brief (deterministic intake)

Build the **rebuild brief**: the verifiable facts that ground every interview
question. Run the deterministic script:

```bash
# Locate the installed Unwind plugin, then load the core helper.
# $0/BASH_SOURCE are unreliable under `bash -c`, so glob the install cache.
UNWIND_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${UNWIND_PLUGIN_ROOT:-}}"
[ -f "$UNWIND_PLUGIN_ROOT/skills/scripts/_resolve-plugin-root.sh" ] || \
  UNWIND_PLUGIN_ROOT="$(ls -dt "$HOME"/.claude/plugins/cache/*/unwind/*/ 2>/dev/null | head -1)"
source "${UNWIND_PLUGIN_ROOT%/}/skills/scripts/_resolve-plugin-root.sh"
ensure_unwind_core || echo "core unavailable — using legacy artifact reading"
node "$UNWIND_PLUGIN_ROOT/skills/scripts/plan-brief.mjs" "$(pwd)"
```

This writes `docs/unwind/.cache/plan-brief.json`. **Read it.** It contains:
- `project` — name, languages, `estimatedComplexity`, file counts.
- `detected` — the **current** stack: `languages`, `ormSources` (data-access framework
  in use, e.g. `{drizzle: 39}`), `endpointMethods`. Use this to recommend concrete
  *targets* per element ("on Drizzle today → keep, or move to X?").
- `perLayer[]` — per layer: file/candidate/symbol counts, coverage %, and
  `[MUST]/[SHOULD]/[DON'T]` tallies. Use these to weight effort and confidence.
- `contracts` — `dataModels`, `sqlDdl`, `dataModelLinks` (ORM↔SQL pairs to reconcile),
  `endpoints` (+ by method). The API/data surface that must be preserved.
- `importGraph` — `foundations` (depended-upon leaves: build first) and `hubs` (most
  depended-upon files). Seeds the phasing order.
- `readiness` — overall coverage % and `provisionalLayers` ( 0` (preserve the existing surface); flag if moving off REST
   breaks the documented endpoint contract.
4. **Datastore & data-access** — DB engine (Postgres / MySQL / SQLite / D1 / Mongo) and
   ORM/query layer (Drizzle / Prisma / Kysely / raw SQL / SQLAlchemy). Recommend from
   `detected.ormSources` and `dataModelLinks`. (The keep-vs-migrate *data* decision is
   B2 §1 — here we pick the access tech.)
5. **Frontend framework** *(if a `frontend` layer exists)* — React / Vue / Svelte /
   Solid, and meta-framework if any (Next / Remix / Astro / SvelteKit), plus
   styling (Tailwind / CSS modules) and state/data-fetching (TanStack Query, etc.).
6. **Per-element modules — go concern by concern.** For each cross-cutting concern the
   brief/architecture surfaced, ask which specific library to use: **auth**
   (Lucia / Auth.js / Clerk / custom JWT), **validation** (Zod / Valibot / Pydantic),
   **messaging/queue** (if a `messaging` layer exists — BullMQ / Cloudflare Queues /
   SQS), **caching**, **background jobs / cron**, **email/notifications**, **file
   storage**, **observability/logging**, **testing framework** (Vitest / Jest /
   Playwright). Recommend the current library (from deps) as the default and offer 1–2
   modern alternatives. Ask explicitly: *"Any specific modules you want to use for any
   part of the solution?"* and capture free-form answers.
7. **Hosting / deployment target** — Cloudflare Workers / Vercel / AWS (Lambda / ECS) /
   Fly / containers / bare VM. This often retro-constrains §1–§4 — if it conflicts with
   an earlier answer, surface the conflict and re-confirm.
8. **High-level architecture confirmation** — replay the **discovered** structure (the
   layers from the brief/architecture.md and their dependencies) and confirm the target
   shape: keep the same layer boundaries? monolith vs modular-monolith vs services?
   Map each documented layer onto a target module. Get explicit sign-off that the
   target architecture preserves the `[MUST]` contracts and data model.

Before leaving B1, **play back the full assembled stack** ("So: TS + Hono on Workers,
REST, Drizzle + D1, React + Tailwind, Zod, Vitest, Cloudflare Queues — correct?") and
get a single confirmation, so the stack is locked as one coherent set, not eight
disconnected picks.

### B2 — Re-use, phasing & validation

9. **Database strategy** — keep live / snapshot+restore / sync (change events, dual
   write). Default informed by `contracts.dataModels` / `dataModelLinks` and table count
   (more ORM↔SQL links ⇒ schema well-pinned ⇒ reuse safer).
10. **Frontend retention** — keep the existing UI and replace only the backend, vs
    rebuild (already partly answered if B1 §5 chose a new frontend framework). Default
    informed by whether a `frontend` layer exists and API-contract rigidity.
11. **Test re-use** — run existing tests against the rebuild, vs rewrite. Default
    informed by the `tests` layer coverage and coupling.
12. **Integrations / scheduled jobs** to preserve — from the contract inventory and
    messaging layer.
13. **Phasing priority & order** — seeded by `importGraph.foundations` (build leaves
    first) and `[MUST]` weighting per layer. Confirm the order and the first slice.
14. **Validation approach & risk tolerance** — parallel-run, equivalence vectors,
    go-live gating.

The user can wrap up at any point ("accept the rest as recommended", "stop here") —
honor it and record the remaining decisions at their recommended values.

### Record every decision

As decisions land, accumulate a list of records (one per question). After the
interview, write the machine-readable record to
`docs/unwind/.cache/rebuild-decisions.json`:

```json
{
  "version": "1.0.0",
  "generatedAt": "",
  "decisions": [
    {
      "id": "RD-1",
      "topic": "Target stack",
      "question": "What stack should the rebuild target?",
      "recommended": "",
      "chosen": "",
      "rationale": ""
    }
  ]
}
```

---

## Phase C — Synthesize (write the plan)

Write `docs/unwind/REBUILD-PLAN.md`, grounded in the brief **and** the confirmed
decisions. Each strategic section records the **decision the user made**, its rationale,
and the brief data that informed it — never an LLM guess.

**CRITICAL:** Never copy content from layer docs. Only reference them (anti-patterns below).

### Output Format: REBUILD-PLAN.md

```markdown
# [Project Name] - Rebuild Strategy

> Generated by Unwind on [timestamp]

## Target Stack

**From:** [detected source stack — language/framework/runtime/datastore/ORM]
**To (assembled in B1):**

| Element | Choice | From (current) |
|---------|--------|----------------|
| Language & runtime | [e.g. TypeScript / Cloudflare Workers] | [detected] |
| Backend framework | [e.g. Hono] | [detected] |
| API contract style | [REST / tRPC / GraphQL] | [detected] |
| Datastore | [e.g. D1 / Postgres] | [detected] |
| Data access / ORM | [e.g. Drizzle] | [detected ormSources] |
| Frontend | [framework + meta + styling, or "retained as-is"] | [detected] |
| Auth | [module] | [detected] |
| Validation | [module] | [detected] |
| Messaging / jobs | [module] | [detected] |
| Testing | [framework] | [detected] |
| Hosting / deploy | [target] | [detected] |
| Other requested modules | [free-form picks from B1 §6] | — |

**Changing:** [parts being re-platformed]   **Staying:** [parts retained]
**Architecture:** [confirmed shape from B1 §8 — monolith/modular/services; layer→module map]

## Executive Summary

**Overall Readiness:** [overall coverage % from the brief] — provisional in: [layers  Each decision below was made during the rebuild interview and is recorded in
> `## Rebuild Decisions`. Assessments cite the deterministic brief.

### Database Strategy
**Decision:** [chosen]  **Why:** [rationale + brief data — dataModels/links/table count]
**If live DB not feasible:** [ ] snapshot+restore  [ ] sync mechanism  [ ] dual-write

### Frontend Retention
**Decision:** [chosen]  **Why:** [rationale + brief data]
**API contract:** preserve exactly [critical endpoints — count from brief]; can evolve [areas]

### Test Re-usability
**Decision:** [chosen]  **Why:** [test-layer coverage + coupling]
**Adapters needed:** [ ] [list]

### Integration Preservation
| Integration | Contract Type | Must Preserve |
|-------------|---------------|---------------|
| [Name] | [webhook/API/job] | [Yes/No + reason] |

---

## Phasing Strategy

> Order seeded by the import graph (foundations first) and [MUST] weighting.

### Phase 1: Foundations
**Build first:** [foundations from the brief — depended-upon leaves]
**Retain / Adapt / Rebuild:** [...]   **Reference:** [layers/xxx/index.md]
**Validation:** [ ] [check]

### Phase 2: Core Logic
[Same structure — highest-[MUST] layers]

### Phase 3: Interfaces (API)
[Same structure — preserve the [count] endpoints]

### Phase 4: Frontend (if rebuilding)
[Same structure]

### Phase 5: Integration & Cutover
**Parallel running:** [old vs new] · **Traffic split** · **Rollback triggers**

---

## Validation Strategy

**Equivalence testing:** [how to prove the rebuild matches — cite test-layer coverage]
**Test vectors:** [ ] existing integration tests pass  [ ] calc outputs match  [ ] API responses identical
**Go-live checklist:** [ ] phase validations  [ ] parallel-run [duration]  [ ] rollback tested  [ ] monitoring

---

## Rebuild Decisions

> The interview answers (also in `.cache/rebuild-decisions.json`).

> One row per question — the B1 stack sub-tree (language, framework, API style,
> datastore, ORM, frontend, per-element modules, hosting, architecture) each get their
> own RD id, then the B2 re-use/phasing/validation decisions.

| ID | Topic | Recommended | Chosen | Rationale |
|----|-------|-------------|--------|-----------|
| RD-1 | Language & runtime | [rec] | [chosen] | [why] |
| RD-2 | Backend framework | [rec] | [chosen] | [why] |
| RD-3 | API contract style | [rec] | [chosen] | [why] |
| RD-4 | Datastore & ORM | [rec] | [chosen] | [why] |
| ... | (frontend, auth, validation, …, architecture) | | | |
| RD-n | Database re-use | [rec] | [chosen] | [why] |
| RD-n+1 | Phasing order | [rec] | [chosen] | [why] |

---

## Layer Documentation References

> These documents contain the detailed specifications. This plan records strategic decisions only.

| Layer | Reference | Coverage |
|-------|-----------|----------|
| Database | [layers/database/index.md](layers/database/index.md) | [%] |
| ... | | |
```

---

## Anti-Patterns

**NEVER do these:**
1. **Copy tables/code from layer docs** — reference the link instead
2. **List every endpoint/table/entity** — that's what layer docs are for
3. **Invent the strategic decisions** — they come from the interview, recorded with rationale
4. **Repeat WHAT to build** — only discuss HOW to approach it

**ALWAYS do these:**
1. **Ground every recommendation in the brief** — cite counts, coverage, the import graph
2. **Record the user's decisions** — both in the plan and `rebuild-decisions.json`
3. **Order phasing by the dependency graph** — foundations first, [MUST] weighting
4. **Flag provisional layers** — where coverage  Rebuild strategy complete. See:
> - `docs/unwind/REBUILD-PLAN.md` — strategy, target stack, and decisions log
> - `docs/unwind/.cache/rebuild-decisions.json` — machine-readable decisions
> - `docs/unwind/architecture.md` — validated architecture overview
>
> The layer documentation contains the detailed specifications. The rebuild plan
> records HOW to approach the rebuild, not WHAT to build.

Analysis is now complete. The natural next step is to **visualize** it — the
dashboard builds its data (`rebuild-graph.json`) on demand, so you go straight there.

**Use AskUserQuestion** to ask whether to continue:
- **Open the dashboard** *(recommended)* — invoke `unwind:uw-dashboard`; it
  (re)generates `rebuild-graph.json` from the current scan + docs and launches.
- **Execute the rebuild** — invoke `unwind:uw-build` to start building in the target
  stack (it interviews you about scope/order and measures completeness as it goes).
- **Export the graph artifact only** — invoke `unwind:uw-graph` to write
  `rebuild-graph.json` without a server (for static deploy / CI / sharing).
- **Pause here** — stop after the plan.

Act on the choice in the same turn; if they pause, tell them how to resume: *"Run
`unwind:uw-dashboard` to explore the graph, or `unwind:uw-build` to start the rebuild."*

> **Pipeline:** scan → analyze → **plan ✓** → dashboard. `uw-graph` is an optional
> artifact-export step, not a gate — the dashboard builds the graph itself.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nearform](https://github.com/nearform)
- **Source:** [nearform/unwind](https://github.com/nearform/unwind)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-nearform-unwind-uw-plan
- Seller: https://agentstack.voostack.com/s/nearform
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.