retrofit-project

What this skill does

# Retrofit Project

Orchestrate a complete documentation retrofit for an existing project with code. Discovers modules, builds a retrofit plan, then autonomously creates feature specs, feature designs, architectural decisions, and a synthesized vision document.

## Context

**You must load the following skills and read the following files before proceeding.**

### Skills
- `katachi:framework-core` - Workflow principles, templates, and task management
- `katachi:retrofit-existing` - Retrofit philosophy and migration strategies

### Existing docs (read if present)
- `docs/planning/VISION.md`
- `docs/feature-specs/README.md`
- `docs/feature-designs/README.md`
- `docs/architecture/README.md`
- `docs/design/README.md`

### Reference Templates
- `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/feature-spec.md` - Feature spec format
- `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/feature-design.md` - Feature design format
- `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/feature-domain-readme.md` - Domain README format
- `${CLAUDE_PLUGIN_ROOT}/skills/working-on-delta/references/feature-specs-readme.md` - Top-level feature index format
- `${CLAUDE_PLUGIN_ROOT}/skills/framework-core/references/ADR-template.md` - ADR format
- `${CLAUDE_PLUGIN_ROOT}/skills/framework-core/references/DES-template.md` - DES format
- `${CLAUDE_PLUGIN_ROOT}/skills/framework-core/references/VISION-template.md` - Vision format
- `${CLAUDE_PLUGIN_ROOT}/skills/framework-core/references/decision-types.md` - ADR vs DES guidance
- `${CLAUDE_PLUGIN_ROOT}/skills/framework-core/references/code-examples.md` - Code snippet guidance
- `${CLAUDE_PLUGIN_ROOT}/skills/framework-core/references/technical-diagrams.md` - Diagram guidance

## Pre-Check

Verify before starting:

1. **Framework initialized**: `docs/planning/` directory exists. If not → suggest `/katachi:init-framework` first.
2. **Project has code**: Source files exist (check for `src/`, `lib/`, `app/`, language-specific files, etc.). If no code → redirect to greenfield workflow (`/katachi:vision`).

## Process

### 0. Check for Existing Scratchpad

Derive the project name from the basename of the current working directory (e.g. `/home/user/workspace/myapp` → `myapp`).

Check if `/tmp/retrofit-project-<project-name>-state.md` exists.

If yes:
- Read the scratchpad
- Summarize progress: current phase, what's completed, what remains
- Ask: "Would you like to continue from where we left off, or start fresh?"
- If continuing → skip to the appropriate phase based on scratchpad state
- If starting fresh → delete the scratchpad and proceed from Phase 1

If no → proceed to Phase 1.

---

### Phase 1: Project Inventory

Dispatch a `katachi:codebase-analyzer` subagent to inventory the entire project:

```python
Task(
    subagent_type="katachi:codebase-analyzer",
    prompt=f"""
Analyze this project structure to create a complete inventory.

## Analysis Type
spec

## Target
[project root directory - read the top-level structure, then explore each major module/package]

## Instructions
Perform a project-wide inventory (not a single-module analysis):

1. **Modules**: Identify each key module/package/directory. For each:
   - Path
   - Purpose (1-2 sentences)
   - Estimated scope (Small / Medium / Large)

2. **Capability Domains**: Group related modules into logical domains
   (e.g., "auth" domain containing login, registration, session modules)

3. **Cross-Cutting Decisions**: Identify architectural choices and patterns:
   - Framework/library choices → ADR candidates
   - Database/storage choices → ADR candidates
   - Repeatable patterns (error handling, logging, testing) → DES candidates
   - For each, note the relevant code locations

4. **Dependencies**: Which modules depend on which (foundational modules first)

## Project Context
{vision_content if exists else "No VISION.md - infer project context from code"}
"""
)
```

Present the inventory to the user as structured tables:

```
## Project Inventory

### Modules
| # | Module | Purpose | Scope | Domain |
|---|--------|---------|-------|--------|
| 1 | src/auth/ | User authentication and sessions | Medium | auth |
| 2 | src/api/ | REST API endpoints | Large | api |
| ... | ... | ... | ... | ... |

### Capability Domains
| Domain | Modules | Description |
|--------|---------|-------------|
| auth | auth/, sessions/ | Authentication and authorization |
| ... | ... | ... |

### Detected Decisions
| # | Topic | Type | Relevant Code |
|---|-------|------|---------------|
| 1 | PostgreSQL for storage | ADR | src/db/, config/database.* |
| 2 | Repository pattern | DES | src/*/repository.* |
| ... | ... | ... | ... |

### Module Dependencies
[foundational modules listed first]

Does this inventory look right? Any modules missing, misidentified, or domains to adjust?
```

Wait for user confirmation/adjustments before proceeding.

Initialize scratchpad at `/tmp/retrofit-project-<project-name>-state.md`:

```markdown
# Retrofit Project State

## Phase
inventory-confirmed

## Inventory

### Modules
| Module | Domain | Scope | Spec Status | Design Status |
|--------|--------|-------|-------------|---------------|
| src/auth/ | auth | Medium | Pending | Pending |
| src/api/ | api | Large | Pending | Pending |

### Decisions
| # | Topic | Type | Status |
|---|-------|------|--------|
| 1 | PostgreSQL | ADR | Pending |
| 2 | Repository pattern | DES | Pending |

## Plan
(not yet built)
```

---

### Phase 2: Retrofit Plan

Build a prioritized plan from the confirmed inventory. Order modules by dependency (foundational first), then by importance.

Present the plan:

```
## Retrofit Plan

### Step 1: Feature Specs (one per module)
1. [ ] [module-a] — [purpose] → docs/feature-specs/[domain]/[name].md
2. [ ] [module-b] — [purpose] → docs/feature-specs/[domain]/[name].md
...

### Step 2: Feature Designs (one per module)
1. [ ] [module-a] design → docs/feature-designs/[domain]/[name].md
2. [ ] [module-b] design → docs/feature-designs/[domain]/[name].md
...

### Step 3: Decisions
1. [ ] [ADR] [framework choice] → docs/architecture/ADR-001-...md
2. [ ] [DES] [error handling pattern] → docs/design/DES-001-...md
...
(Additional decisions may be discovered during design analysis)

### Step 4: Project Structure
- [ ] Domain READMEs for feature-specs/ and feature-designs/
- [ ] Top-level README indexes
- [ ] Architecture and design indexes

### Step 5: Vision
- [ ] Synthesize VISION.md from all documented features

This plan will execute autonomously. Ready to proceed?
```

Wait for user confirmation. This is the last approval before autonomous execution.

Update scratchpad with the full plan.

---

### Phase 3: Execution

Execute the plan autonomously using subagents. Write all output files directly.

#### Step 1 — Retrofit Specs (parallel)

For each module in the plan, dispatch a `katachi:codebase-analyzer` subagent **in parallel** (spec mode):

```python
Task(
    subagent_type="katachi:codebase-analyzer",
    prompt=f"""
Analyze this code to create a feature specification.

## Analysis Type
spec

## Target
{module_path}

## Project Context
{vision_content if exists else "Infer project context from code"}
"""
)
```

For each result:
- Adapt the output to match the **feature-spec template** (not the codebase-analyzer's raw spec format)
- Add a Retrofit Note at the top:
  ```markdown
  ## Retrofit Note

  This spec was created from existing code at `[path]`.
  Retrofit date: [today's date]

  ---
  ```
- Write to `docs/feature-specs/[domain]/[name].md`

After all specs are written:
- Create domain README files using the `feature-domain-readme.md` template
- Create/update `docs/feature-specs/README.md` using the `feature-specs-readme.md` template
- Update scratchpad marking all specs as done

Update scratchpad with a summary of specs created, then proceed immediately to designs.

#### Step 2 — Retrofit Designs (parallel)

For each module, dispatch `katachi:codebase-analyzer` **in parallel**