/codd-evolve

name: codd-evolve
description: |
  Conversationally evolve an existing CoDD project. Use when the user describes a functional change in natural language ("add logout button", "change course model to master + delivery target", "remove daily log step") and you need to update requirements, design docs, lexicon, source code, and tests together while maintaining CoDD coherence. Brownfield modification, NOT greenfield generation, NOT pure bug fix.

CoDD Evolve — Conversational Brownfield Evolution

Take a Lord-style natural-language change request and automatically determine which design docs, lexicon entries, source files, and tests must move together to preserve CoDD coherence. The user expresses intent; this skill figures out scope.

When to Use

• The user describes a **functional change** to an existing system, not a bug
• Examples of trigger phrases:
• "Add a logout button to the admin nav"
• "Change course management — courses should be a shared master with separate delivery targets"
• "Restructure the learner list to drill down: facility → learner → course → progress"
• "Remove the daily log append step from the karo completion flow"
• "受講者管理を施設フィルター起点に変更"
• The user does NOT want to think about *which* design docs, lexicon entries, or source files to touch
• The project is already CoDD-initialized (has `codd/codd.yaml` and at least the design doc layout)

Do NOT use this for:

• Greenfield generation from scratch — use `/codd-init` then `/codd-generate`
• Pure bug fix where requirements and design are correct — use `codd fix` or `codd fix [PHENOMENON]`
• Reverse-engineering an undocumented codebase — use `codd extract` (or `/codd-restore`)
• Single-doc impact analysis only — use `/codd-impact`
• Code-only refactoring with no behavioral change — use `codd propagate`

What This Does — Role Separation

This skill makes a single contract explicit:

| Layer | Who decides | What | |-------|-------------|------| | Intent | **User** | "I want X" in natural language | | Strategic constraints | **User** | North star, hard prohibitions, breaking-change tolerance | | Impact scoping | **This skill** | Which design docs, lexicon, source files, tests are affected | | Doc updates | **This skill + CoDD** | Update requirements + every affected design doc in coherent order | | Lexicon updates | **This skill** | Detect new terms, ask user before adding, then update lexicon | | Implementation | **CoDD CLI** | `codd implement` from updated design | | Verification | **CoDD CLI** | `codd verify` — must reach red 0 | | Coherence finalization | **CoDD CLI** | `codd propagate` for cross-doc consistency | | Failure judgment | **You (orchestrator)** | Decide retry vs ask user vs abort | | Final approval | **User** | Review the PR / diff post-hoc |

The user must never have to choose *which file* to touch.

Workflow

Step 1 — Confirm prerequisites

Before starting, verify:

1. Current directory is a CoDD-initialized project (`codd/codd.yaml` exists) 2. Working tree is clean OR uncommitted changes are intentional (warn the user otherwise) 3. `codd verify` currently passes (red 0) — if not, the user should fix existing red first, per `codd fix [PHENOMENON]` prerequisite 4. If `codd verify` returns exit 0 with **silent stdout** (a known mode where build/test phases run but emit no text), fall back to `codd dag verify` for an explicit red-count readout. Use both signals when the baseline is uncertain. 5. If runtime verification_test nodes are unsuitable for the local environment, prefer an explicit config or skip over silent omission: set `verify.verification_timeout.total_seconds` / `per_node_seconds`, or run `codd verify --runtime --runtime-skip verification-test` and preserve the reported SKIP evidence.

If red exists, STOP and surface it. Do not attempt to layer new changes on a red baseline.

Step 2 — Parse intent and classify

Classify the user's request into one of:

| Type | Marker | Likely affected docs | |------|--------|---------------------| | `add_feature` | "add X", "新規追加" | requirements + at least one design doc + lexicon (new terms) + new source + new tests | | `change_behavior` | "change X to Y", "〜に変更" | requirements + affected design docs + lexicon (term-meaning shift) + modified source + updated tests | | `change_data_model` | "data model", "schema", "table", "entity" | database_design + api_design + lexicon + migrations + source + tests | | `change_ux` | "UI", "screen", "navigation", "画面" | ux_design + frontend source + frontend tests | | `remove_feature` | "remove X", "削除" | requirements (mark removed) + design docs (remove sections) + source (remove) + tests (remove or update) + lexicon (deprecate term) | | `cross_cutting` | Touches auth/permissions/i18n/tenancy | auth_design + every callsite + tests for every role |

If classification is ambiguous, ask one clarifying question (see Step 3).

Drift detection against existing design

After classification, scan the affected design docs for **pre-existing references to the proposed change**. Examples:

• The intent says "add logout button to admin nav," but `ux_design.md` already documents a logout entry in the tenant_admin / learner sidebars (impl never caught up).
• The intent says "add delivery_target table," but `database_design.md` has an Open Question (OQ-DB-NN) that proposes the same structure under a different name.

When such drift is found, classify it:

• **Drift A — broader-than-intent**: design covers more roles/cases than the intent. Either (a) flag to the user and ask whether to keep the narrower intent or align to the design, or (b) treat as a Step 3 gate-5 "ambiguous scope" trigger.
• **Drift B — design proposed, impl absent**: an Open Question or TODO matches the new intent. Reuse the existing terminology and mark the OQ as resolved.
• **Drift C — contradiction**: design says X, intent says not-X. Halt as a Step 3 gate-3 "structural impossibility."

Recording drift in the report prevents si