retrofit

Project Retrofit

Retrofit an existing project to the keel workflow, or migrate legacy keel to the new specification.

Language Rules

Support questions in Chinese and English
Reply uniformly in Chinese
Generate documents in Chinese

Quick Start

In one sentence: Adapt an existing project to the keel workflow, or migrate legacy keel to the new specification.

Most Common Usage: /retrofit(auto-detect project state)

/retrofit --realign → Specification upgrade rescan: check 00-baseline.md against the current baseline.v1 for gaps (⛔ only fill in structure, do not modify body text with source annotations). See references/realign.md; recommended user entry /pipeline realign

Not suitable? New project→/pipeline init, add feature→/feature

Trigger Conditions

The user wants to adapt an existing project to the keel workflow
The user needs to standardize project documentation
The user wants to migrate or upgrade existing keel documents
The project lacks documentation and needs a maintainable baseline

Boundary with realign

retrofit and realign (specification upgrade rescan)complementary, not overlapping，with frontmatter + spec_version field as the primary criterion: the document's top YAML frontmatter exists and contains a valid spec_version → trust the metadata, classify as realign（/pipeline realign), regardless of whether the body is missing F-XXX numbering (numbering completion is handled by the additive gap process within realign); otherwise (no frontmatter / no spec_version / no keel) classify as retrofit. See ../pipeline/references/realign.md § Boundary with retrofit.

Workflow

1. 扫描项目结构
   │
   ▼
2. 检测项目状态
   │
   ├── 无 docs/devdocs/ ──────────────────► 建立项目基线
   │
   ├── 有 00-baseline.md 且无 01~04 ────► 基线已建，终态，无需改造
   │
   ├── 有 keel（符合规范）────────────► 无需改造
   │
   └── 有 keel（旧版）────────────────► 版本迁移
   │
   ▼
3. 呈现方案 + AskUserQuestion 确认
   │
   ▼
4. 执行
   │
   ├── 建立基线：调查 → 校验 → 推导 → 提问 → 落盘 00-baseline.md
   └── 版本迁移：更新迁移文档 → 生成/更新 docs/devdocs/
   │
   ▼
5. 收尾
   │
   ├── 基线路径：不产报告（建立记录已在基线内）
   └── 版本迁移：生成 00-retrofit-report.md

Plan Confirmation Specification

After scanning the project structure and detecting the state,present the retrofit strategy and use AskUserQuestion to let the user choose an execution branch, and only generate/update documents after confirmation.

Version Migration Scenario

After presenting the specification check results and the migration action list, let the user choose:

Legacy keel detected, recommended migration strategy:

Full migration(recommended) - automatically complete all document migrations

Selective migration - select the document items to migrate (after selection, specify the exact migration scope)

Generate difference report only - do not migrate documents, only output a difference report Please choose a migration method.

Selective Migration Additional Interaction: after the user selects option 2, present the difference list and let the user check the documents/sections to migrate, and execute only after confirming the scope.

Establish Baseline Scenario

After presenting the investigation coverage and verification results, let the user choose:

The investigation and verification results are as follows, please confirm or adjust:

Confirm investigation results, start establishing the baseline

Supplement materials(specify missed documents / issues / historical materials) and then investigate again

Adjust baseline scope(which sections to build first, which to mark as unknown)

The plan must include

Establish baseline: Investigation coverage (materials sourced so far) → Verification results (counts of: corroborated / unverifiable / contradicts code) → List of items to ask about → Estimated "unknown" ratio → Risks and cautions

Version migration: Specification check results → Migration action list (including scope of impact and risks) → Migration mode (full/selective/report only)

Constraints

Projects that comply with the current specification: Directly inform the user that no rework is needed and exit, without entering branch selection
Before the user chooses: only display the options, do not write to any files
After the user chooses: generate according to the branch docs/devdocs/ documents under
Selective migration: can only be executed after the user specifies the migration scope; the scope must not be guessed
Baseline draft: before writing to disk, a draft with source annotations must be shown for user confirmation; items on which the user has not expressed a position remain 推导待确认, and must not be upgraded

Project status detection

Detection logic

0. 带 --realign 标志？
   │
   ├── 是 → 直接进 realign 子流程（见 references/realign.md），跳过下方全部检测
   │        ⛔ 只补结构（缺失章节 / frontmatter 字段），不改带来源标注的正文
   │
   └── 否 → 继续
   │
   ▼
1. docs/devdocs/ 是否存在？
   │
   ├── 不存在 → 建立项目基线
   │
   └── 存在 → 有 00-baseline.md 且无 01~04？
       │
       ├── 是 → 基线已建（第三终态）→ 无需改造，提示下一步 /feature
       │
       └── 否 → 规范符合性检查
           │
           ├── 符合当前规范 → 无需改造
           │
           └── 不符合 → 版本迁移流程

⛔ "Baseline established" is a third terminal state on par with "complies with specification", not "old version pending migration".

A baseline project has not a single numbered item; if it goes directly into the specification compliance check, it will be judged as "missing F/US/AC numbering ⚠️ migration needed", so the version migration processtries to migrate the baseline project that was just established back to the old numbering form——the user runs it a second time /retrofit and will run into this infinite loop. The criterion must be short-circuited before the specification checkbefore.

The criterion isexistence, not exclusivity: a baseline project may have other artifacts such as 05-bugfix-log.md and 00-context.md, and they do not affect the "baseline established" determination. Only check whether 01~04 are present.

Specification compliance check list

Check item	Check content	Specification requirement
Numbering system	F-XXX, US-XXX, AC-XXX	Required
Test numbering	UT-XXX, IT-XXX, E2E-XXX	Required
Traceability matrix	F → US → AC → test mapping	Required
File naming	01-requirements.md, 03-test-cases.md, etc.	Required
Section completeness	Required sections for each document	Required
Skill collaboration	Annotate collaborating Skill	Suggested

Version migration process (keel exists but does not comply with specification)

Executed when existing keel documents are detected but do not comply with the current specification. For the complete detailed specification for Step M1-M4 (specification check report / difference list format / user confirmation wording / numbering migration example / file renaming / traceability matrix generation), see references/version-migration.md。

Key points:

M1 Specification check: generate a "detection results" table (file / status / issue)
M2 Generate difference list: numbering system + file structure + traceability matrix + section supplements
M3 User confirmation: AskUserQuestion with three options (full migration / selective / report only)
M4 Migration execution: numbering + renaming (git mv preserves history) + traceability matrix

Establish project baseline (no keel)

Executed when the project has no keel documentation. For the full process (investigation scope / validation rules / source annotation / questioning discipline / writing to disk), see references/new-project-retrofit.md, and for the artifact shape see templates/baseline-template.md。

The baseline records only information that cannot be reconstructed by re-scanning the code. Modules / interfaces / data objects / tech stack go to docs/codebase-insight.md; current progress / to-dos go to docs/devdocs/00-context.md。

Key points:

Step 1 Investigation: delegate codebase-insight to survey + README / CHANGELOG / git commit messages / issues·PRs / actually running builds and tests; if the environment provides cross-session history retrieval (such as /mem-search), also retrieve "why it was decided this way back then"; ⛔ its conclusions likewise go through Step 2 validation and source annotation, and are not exempt from checking just because they come from a memory store
Step 2 Validation: use the code to check every verifiable statement in the document → 已佐证 / 未可验 / 与代码矛盾
Step 3 Derivation: draft a draft with evidence annotations, clearly stating "based on what" for each item
Step 4 Questioning: ask only about items that cannot be derived, have weak evidence, or are found contradictory during validation; ⛔ every question must have an "I don't know either" exit
Step 5 Write to disk:docs/devdocs/00-baseline.md, do not produce 01~04

Existing code is not numbered. 01-requirements.md is created by the first /feature , andF-001 starts from a new requirement. Between the completion of the rework and the first requirement,/board、/test-cases、/verify will refuse to run—this is correct behavior, there is no requirement yet, so of course requirements cannot be reviewed.

Rework report

Generated only for the version migration path 00-retrofit-report.md, including a migration action checklist (which numbers were changed, which files were renamed). For the detailed template, see templates/retrofit-report-template.md。

The baseline path does not produce a report: the original report's "number allocation" table is voided in its entirety (numbers are no longer produced), the "document status" table collapses into one row (only one baseline is produced), and the remaining "items to be improved" and "next-step suggestions" have been merged into the baseline's "establishment record" section—it follows the baseline, so that whoever reads the baseline next can see the limitations of this baseline.

Key rules: the baseline is not the endpoint. New requirement → /feature; supplement the project background or upgrade 推导待确认 to 用户确认 → /requirements --context(written to 00-baseline.md）。

Workspace topology (retrofit path): after a successful rework anddocs/devdocs/ is generated, execute Task: /workspace-topology reconcile. This skill writes AGENTS.md 's workspace: block itself, and if there is no declaration, asks once for the mode and code root and writes the declaration to disk. See ../workspace-topology/SKILL.md。

Memory sync (mandatory on the success path): after a successful rework anddocs/devdocs/ is generated, execute Task: /agent-memory --update to sync AGENTS.md (a keel project will include a workflow routing section). Writing AGENTS.md follows agent-memory's narrow exception (see the constraint below, "The Write tool is only used to write to docs/devdocs/"); this Skill does not directly Write that file. Failure semantics: ℹ️ does not block the rework delivery, and blockers are recorded in the report.

Skill collaboration

Scenario	Collaborating Skill	Description
Code inventory	`/codebase-insight`	Delegated in baseline Step 1, producing the inventory layer to generate candidates for questioning
Baseline incremental completion	`/requirements --context`	Upgrade `未知` / `推导待确认` to `用户确认`
Requirement review	`/requirements`	Review requirement documents (a baseline project must first have `01`, created by the first `/feature` )
Design review	`/system-design`	Review system design (same as above; requirement document required first)
Test cases	`/test-cases`	Improve test case design (same as above; requirement document required first)
New features	`/feature`	Add new features after refactoring
Bug fixes	`/bugfix`	Fix issues after refactoring
Test quality	`/testing-guide`	Check test effectiveness
File operations	`/git-safety`	Use git mv when renaming files

Constraints

Phase boundary constraints (highest priority)

⛔ Do not continue: the documentation phase must not produce implementation code(Recovery method: use /dev-workflow to perform coding)
The Write tool is only used to write docs/devdocs/ Markdown documents under ; narrow exception: after successful refactoring, delegate to agent-memory to write its managed memory file (AGENTS.md/CLAUDE.md import lines/.claude/rules/devdocs-state.md), other business files are still prohibited

Plan confirmation constraints

After scanning the project + detecting status, you must present the plan and wait for the user to choose an execution branch
The plan must include the refactoring strategy and investigation coverage and estimated unknown ratio (baseline establishment) or migration action list (version migration)

Detection constraints

You must first detect the project status (no keel / baseline established / old version / compliant with specification)
You must scan common documentation directories

Migration constraints

A difference list must be generated before migration
User confirmation is required before migration
File renaming must use git mv
The valid content of existing documents must not be deleted

Baseline content constraints

⛔ 00-baseline.md Module tables / interface tables / data object tables / dependency graphs / tech stack lists / directory structure trees must not appear（→ codebase-insight.md）
⛔ Current branch / uncommitted changes / completion rate / to-dos must not appear（→ 00-context.md）
⛔ "This behavior must be preserved" must not be derived from implementation details——The greatest harm is not obsolescence, but writing implementation accidents as design intent
⛔ Assertions without source annotations must not appear; if it cannot be derived, mark it as 未知
⛔ 推导待确认 It must not be upgraded to 用户确认
⛔ Every question must provide an "I am not sure either" exit, and choosing it is not a failure——without an exit, the false information produced by users being forced to guess is worse than marking 未知 worse
Three elements of the guardrail section (decision / which changes are constrained / basis)Do not write it if any one is missing
Each "known unknown" entry must state the "safe default action before confirmation"

Output constraints

The baseline path only produces 00-baseline.md, not 01~04

Error handling

See references/error-handling.mdfor details (insufficient investigation materials, project has no documentation at all, migration conflicts)

Sub-agent summary format

When this Skill runs as a sub-agent, return the following structured summary:

skill: retrofit
status: success | failed | partial
summary:
  headline: "项目基线已建立，5 项未知待补"
  details:
    path: baseline | version-migration
    baseline_established: true
    adoption_commit: "a1b2c3d"
    counts:
      用户确认: X
      已有文档: X
      推导待确认: X
      未知: X
    evidence_conflicts: X
    build: "pass | fail | none"
    tests: "pass | fail | none"
blockers: []
output_files:
  - docs/devdocs/00-baseline.md
new_ids: {}
next_recommended:
  skill: feature
  args: ""

Output files

Baseline path：

docs/devdocs/
└── 00-baseline.md          # 项目基线（唯一产物）

Attached (produced by each delegated skill, not written by this skill):docs/codebase-insight.md（codebase-insight）、AGENTS.md domain terminology and architecture decision section (agent-memory）。

Version migration path：

docs/devdocs/
├── 00-retrofit-report.md    # 迁移报告
└── <按迁移范围更新的既有 01~04 文档>

About this skill

Language Rules

Quick Start

Trigger Conditions

Boundary with realign

Workflow

Plan Confirmation Specification

Version Migration Scenario

Establish Baseline Scenario

The plan must include

Constraints

Project status detection

Detection logic

Specification compliance check list

Version migration process (keel exists but does not comply with specification)

Establish project baseline (no keel)

Rework report

Skill collaboration

Constraints

Phase boundary constraints (highest priority)

Plan confirmation constraints

Detection constraints

Migration constraints

Baseline content constraints

Output constraints

Error handling

Sub-agent summary format

Output files