Prospec Knowledge Update

---
name: prospec-knowledge-update
description: "Incremental Knowledge Update - Parse delta-spec.md to identify affected modules, scan source code, and update module README, index.md, and module-map.yaml incrementally. Triggers: knowledge update, incremental update, sync knowledge, update docs, 更新知識, 增量更新, 同步知識, 更新文件"
---
<!-- Generated by `prospec agent sync`. Do not edit — this file is regenerated on every sync. -->

# Prospec Knowledge Update Skill

## Activation

When triggered, briefly describe:
- That you'll parse delta-spec.md to identify affected modules
- Only affected modules will be scanned (not the entire codebase)
- Module README.md (Recipe-First format), prospec/index.md, and module-map.yaml will be updated incrementally
- User-written sections (prospec:user-start/end) are always preserved

## Language Policy

Write each generated document in the language the Constitution's Language Policy rule assigns to **its path** — change artifacts and their archived summaries in the project's artifact language, the trust zone (Knowledge base, Feature Specs, index) in English. One skill run may write both. Keep code, identifiers, technical terms, and git commit messages in English.
## CLI Prerequisite (required)

> The prospec CLI is a required file for this skill — its deterministic steps call `prospec`
> commands. Probe BEFORE any other step; there is no manual fallback.

1. Run `prospec --version` (Bash).
2. **Command not found / not executable** → STOP. Ask the user to install the prospec standalone
   executable — the one-click installer script from the project README (macOS/Linux `install.sh`,
   Windows `install.ps1`) or a release binary from GitHub Releases; prospec is NOT published to
   npm. Then re-run this skill.
3. **Version older than 2.0.0** → STOP. Report the installed vs required version
   and ask the user to upgrade, then re-run this skill.

Hand-executing a CLI-owned mutation is NEVER the fallback — that re-introduces the
nondeterministic serialization this contract exists to remove.

## Startup Loading

1. [STABLE] Read `prospec/ai-knowledge/_conventions.md` — team conventions (incl. the Module READMEs pointer)
2. [STABLE] **MANDATORY** — Read `prospec/ai-knowledge/_module-readme-conventions.md` for the canonical README output format (dated marker, Core section order, `# {ProperName}` title, `prospec:auto`/`prospec:user` marker contract, and the Project Section Extensions registry — the only extension authority, not `.prospec.yaml`)
3. [DYNAMIC] Read `.prospec/changes/[name]/delta-spec.md` — identify ADDED/MODIFIED/REMOVED requirements
4. [DYNAMIC] Read `prospec/index.md` — current module index
5. [DYNAMIC] Read `prospec/ai-knowledge/module-map.yaml` — current dependency graph (if exists)

## Progressive Knowledge Loading Strategy

| Layer | Files | When to Load | Token Budget |
|-------|-------|-------------|-------------|
| **L0** | `AGENTS.md` / `CLAUDE.md` | Every conversation (auto-injected via agent config) | Agent-injected — out of `knowledge-size` scope |
| **L1** | `prospec/index.md` + Core Conventions + Context-specific artifacts | At startup (acts as entry point and current task context) | ≤ 2500 tokens per file |
| **L2** | `prospec/ai-knowledge/modules/{name}/README.md` (+ each linked `{sub-module}.md`) | When Skill identifies related modules from L1 keywords | ≤ 2000 tokens per module file — README and each linked sub-module alike; also ≤ 100 lines |
| **Spec** | `prospec/specs/features/**/*.md` + `prospec/specs/product.md` | When Skill identifies related features | ≤ 5000 tokens per spec file — a slice under `features/{feature}/` is measured alike |
| **Demand** | Demand Conventions (lessons ledger, playbook, …) | When their topic is relevant — read in slices, never whole | ≤ 20000 tokens per file |
| **Skill** | deployed `SKILL.md` and its `references/*.md` | Injected per station by the harness | ≤ 5000 tokens per skill, ≤ 2500 tokens per reference — measured only where this project holds the skill template sources |
| **L3** | Source code files | When Agent needs implementation details | No limit (read on demand) |

> Every budget below L0 comes from `.prospec.yaml` `knowledge.token_budget` (the numbers reflect this project's current settings — the defaults when a field is unset); over-budget files WARN via `prospec check` `knowledge-size` (warnings start at 0.85 of the limit to provide a pressure signal before drift), never a build breaker — and each finding names the convergence path for its surface. L0 is agent-injected config, out of the check's scope.

**Principles:**
1. L0 answers "how to use skills" — L1 answers "where to look" and "what to do" — L2 answers "what it does" (Feature Spec) and "how to modify" (Module README) — L3 answers "how to write"
2. Each layer must NOT duplicate information available in a lower layer
3. The README (plus any linked `{sub-module}.md`) is the only knowledge per module — no api-surface.md, dependencies.md, or patterns.md
4. Sub-modules are an L2 sub-layer reached via the README's `## Sub-Modules` links — never listed in `prospec/index.md`

**Token Budget Reminder:** After updating, verify the affected README stays within budget. If it overflows and has a content-rich, functionally-independent sub-area, extract a sub-module (see Phase 3a) rather than trimming away useful detail; otherwise trim Key Files and Public API, keeping Modification Guide and Pitfalls intact. Canonical rules: `prospec/ai-knowledge/_module-readme-conventions.md`.

## Core Workflow

### Phase 1: Run the Mechanical Update (CLI)

Run `prospec knowledge update --change [name]` (Bash) — or `--module <name>` (repeatable) when there
is no delta-spec (quick changes, manual refresh). The CLI owns every deterministic step: parsing
delta-spec REQ ids (`REQ-{MODULE}-{NNN}` → lowercased module; feature-prefix ids resolved via
feature-map + `metadata.related_modules`, never minting a phantom module), creating a skeleton
README for a genuinely NEW module, banner-deprecating REMOVED modules (the README gets the banner
and stays; the `module-map.yaml` entry is removed, so the module drops out of the regenerated
index table), adding new `module-map.yaml` entries, and regenerating the `prospec/index.md`
auto block from module-map.

Read its report: `created` (skeletons to fill), `deprecated`, **`README content pending`** — the
judgment worklist this skill exists for — and **`stamp-only (diff-attributed)`**: modules a
working-tree diff attributes but no delta-spec REQ named (typically a generated artifact pulling in
its module), which need only a freshness stamp, not a README edit. The CLI never rewrites an existing
README: its `prospec:auto` block carries authored knowledge that a mechanical re-render would gut.

> **Phase 1 Gate** — proceed when:
> - [ ] `prospec knowledge update` ran (change mode or `--module` mode)
> - [ ] the created / deprecated / readme-pending worklist captured from its report

### Phase 2: Scan Affected Modules

For each affected module:
1. Locate module paths from `module-map.yaml` (or infer from module name)
2. Scan source files (max 20 key files per module)
3. Infer file descriptions from naming patterns (service.ts, test.ts, etc.)
4. Read the module's existing `README.md` **and any `{sub-module}.md`** linked from its `## Sub-Modules` section — an update may need to refresh a sub-module, not just the main README

> **Phase 2 Gate** — proceed when:
> - [ ] each affected module's source files located and scanned (≤ 20 key files per module)
> - [ ] existing README.md and any linked `{sub-module}.md` read for each module

### Phase 2.5: Format Drift Check (consent-gated)

Before writing, check whether the **existing** Knowledge files' format still matches the current
templates/conventions — independent of this change's content:
- `prospec/index.md` column schema vs the canonical INDEX columns and `_module-readme-conventions.md`
- each affected module `README.md` by running `prospec validate module-readme <module>` against
  `_module-readme-conventions.md`; use its source-anchored findings for the dated marker, Core grammar,
  registry, and marked extension instances rather than inventing a second checklist
- `_conventions.md` `prospec:auto`/`user` marker structure

If a file's **format** has drifted (sections/columns/markers differ from the current conventions),
list the specific drift and **ask the user whether to update the format** in this run. Migrate the
format only on consent — never rewrite authored content. If the user declines, do the content
increment in the existing format and note the declined format update. When there is no drift, proceed
silently — do not prompt.

An accepted migration preserves every marked extension section and all freeform user notes inside the
user block. The registry defines only marked sections; an unmarked user heading remains a freeform note.

> **Phase 2.5 Gate** — proceed when:
> - [ ] existing Knowledge format compared against current conventions/templates
> - [ ] any drift listed and a format update applied only on user consent (or declined and noted)

### Phase 3: Update README Content (judgment)

> The mechanical writes already happened in Phase 1. What remains is the CONTENT — reading the code
> and writing knowledge prose — which is exactly what the CLI does not do.

#### 3a: Module README.md (created skeletons + readme-pending) — Recipe-First Format

For CREATED modules (skeleton scaffolded by the CLI in Phase 1):
- Fill `prospec/ai-knowledge/modules/{module}/README.md` with real content in the **canonical
  Recipe-First structure** defined in `prospec/ai-knowledge/_module-readme-conventions.md` (the
  sole authority for section order, the `# {ProperName}` title, and the `prospec:auto`/`prospec:user`
  marker contract — do not restate the skeleton here, matching `prospec-knowledge-generate`).

For README-PENDING modules (the CLI's judgment worklist):
- Read the existing README.md
- Update the `prospec:auto-start/end` section CONTENT by hand from what you scanned in Phase 2 —
  this is deliberate judgment work, never a mechanical re-render
- **Preserve** all content within `prospec:user-start/end` markers, including marked extension sections and freeform user notes
- Update Key Files table, Public API list, dependency info
- **Refresh Modification Guide** — if implementation patterns changed, update guidance
- **Refresh Ripple Effects** — if new dependencies were added, update impact list
- **Pair universal conventions with executors** — when adding or editing a universal prose convention in a module README (e.g. "EVERY X must Y" or "all sinks must call Z"), ensure an executor test exists in `tests/contract/` (or the project's contract suite) to mechanically enforce it; a checker with no executor is not a gate.
- **Maintain sub-modules** — if the module already has `## Sub-Modules` links, update the affected `{sub-module}.md` (and the link's one-liner) instead of cramming the detail back into the README. If the change pushes the README over budget and a content-rich, independent sub-area now exists, extract a new sub-module (`{module}/{sub-module}.md`) and add it to `## Sub-Modules` — do NOT add it to `prospec/index.md`.

#### 3b: Module README.md (REMOVED)

Review the banner's reason wording; refine it in place if the delta-spec description reads poorly as prose.

#### 3c: module-map.yaml (curated single source)

The module table's curated columns — Keywords, Aliases, Rationale, Description, and Depends On (via
`relationships.depends_on`) — live in `prospec/ai-knowledge/module-map.yaml` as the single source;
`prospec/index.md`'s `prospec:auto` block is **generated** from it (`updateIndex`). Curate here,
NOT by hand-editing the index table (it gets regenerated).

The CLI added/removed the entries in Phase 1 — an ADDED entry is a SKELETON (`"<name> module"`
description, guessed paths). What remains is curation (judgment):

- Curate the ADDED entries: real `description`, `keywords`, `aliases`, `rationale`, `paths`, `relationships`
- Update `keywords`/`aliases`/`rationale`/`description`/`relationships` for MODIFIED modules
- Preserve each existing module's `category` (do NOT re-guess it); for an ADDED module, derive an ordered `category: [primary, …]` consistent with existing grouping and write it
- After curating, re-run `prospec knowledge update --module <curated-modules>` so the index auto block regenerates from the curated map
- Skip if module-map.yaml doesn't exist

#### 3d: prospec/index.md (CLI-generated — never hand-edit the auto block)

On a project that curated in index.md, the first run **backfills** the curated content columns
(Keywords/Aliases/Rationale/Description) into `module-map.yaml` (no-clobber) before regenerating.
**Depends On** derives from `relationships.depends_on`; a module-map lacking it renders `—` until
populated (re-run `prospec-knowledge-generate`).

After the re-run, verify (read, don't write):
- ADDED modules appear as Active; REMOVED modules are GONE from the table (their README keeps the deprecation banner)
- the Progressive Knowledge Loading Strategy section (outside the auto block) is intact

#### 3e: Stamp Knowledge Freshness (`prospec knowledge verify`)

After reviewing/updating the README content for each confirmed module, run `prospec knowledge verify <modules...>` (Bash) to stamp `last_verified` in `prospec/ai-knowledge/module-map.yaml`. `prospec knowledge verify` is the sole writer of `last_verified`, ensuring mechanical tools do not auto-stamp freshness without explicit review of the knowledge prose. The affected modules to stamp are the delta-spec REQ-prefix modules ∪ the modules a working-tree diff attributes through the module map (generated artifacts included); of that union, the diff-attributed modules that no REQ named are the subset Phase 1's report flags as `stamp-only`. Passing all of them (e.g. `prospec knowledge verify <module1> <module2>...`) marks them fresh. If the project has a knowledge-sync mechanical gate, re-run it after the feature commit and before pushing — before the commit it sees only an empty range.

## Output Contract

> After running, self-assess and emit a concise Output Summary. Every Success Criterion must be objectively checkable (file existence / grep / test result / count) — no subjective adjectives.

### Success Criteria
- [ ] every affected module README updated
- [ ] prospec/index.md and module-map.yaml synced
- [ ] knowledge freshness stamped via `prospec knowledge verify` for reviewed modules
- [ ] REMOVED requirements marked deprecated (not deleted)

### Failure Conditions
- no delta-spec and no manually specified module
- an affected module left stale

### Output Summary
Emit one line: `Met N/M | Unmet: <items> | Overall: PASS|WARN|FAIL | Next: <one-line>`

## NEVER

- **NEVER** overwrite content between `prospec:user-start/end` markers — preserve marked extension sections and freeform user notes
- **NEVER** migrate an existing Knowledge file's format without listing the drift and getting user consent (Phase 2.5) — content increments are fine, format rewrites need a yes
- **NEVER** delete module directories for REMOVED requirements — mark as deprecated only
- **NEVER** scan the entire codebase — only scan modules identified from delta-spec
- **NEVER** run without either delta-spec.md or manual module specification — one input source is required
- **NEVER** hand-edit the prospec/index.md auto block — it is CLI-generated from module-map; curate in module-map and re-run `prospec knowledge update`
- **NEVER** ignore module-map.yaml when it exists — dependency graph must stay in sync
- **NEVER** generate api-surface.md, dependencies.md, or patterns.md — all info goes in README.md (or its sub-module files) only
- **NEVER** exceed 100 lines per module README or sub-module — when it overflows, extract an independent sub-area to `{module}/{sub-module}.md` and link it from `## Sub-Modules` before resorting to lossy trimming
- **NEVER** list sub-modules in `prospec/index.md` or `module-map.yaml` — they are reached only via the parent README's `## Sub-Modules` links

## Error Handling

| Scenario | Action |
|----------|--------|
| delta-spec.md not found | Re-run with `--module <name>` (repeatable) — the CLI refuses change mode without a delta-spec |
| module-map.yaml not found | Skip module-map update, proceed with README and prospec/index.md only |
| Module directory doesn't exist (MODIFIED) | Run `prospec knowledge update --module <name>` — manual mode scaffolds the skeleton; then fill it |
| Auto/user marker conflict while editing | Prefer your new auto content, always preserve user sections |
| Source scan returns 0 files | Generate minimal README with module name only, warn user |
| README exceeds 100 lines after update | Trim Key Files and Public API; keep Modification Guide and Pitfalls |

## Next-Step Handoff

After the Output Summary, recommend the next step in the SDD workflow order
(`story → plan → tasks → implement → review → verify → knowledge-update → archive`, then periodic `learn`) — read
`metadata.yaml` status and `prospec/ai-knowledge/_status-lifecycle.md` (review and learn own no
status transition, so follow this order, not status alone). Provide the direct, actionable Skill
identity or CLI command for the next step (e.g. `prospec-plan`), allowing smooth continuation
without blocking on a separate confirmation turn. If the stage is terminal (`archived`), the linear
flow is complete — point to periodic `prospec-learn` rather than a workflow successor. If the result
does not advance (e.g. verify grade B/C/D), say so and point to the corrective step instead of
offering the next skill.