Prospec Knowledge Generate

---
name: prospec-knowledge-generate
description: "Generate AI Knowledge - Read raw-scan.md, analyze project structure, autonomously decide module boundaries, and produce Recipe-First module READMEs and index. Triggers: generate knowledge, analyze project, module split, 產生知識, 知識庫, 分析專案, 模組拆分"
---
<!-- Generated by `prospec agent sync`. Do not edit — this file is regenerated on every sync. -->

# Prospec Knowledge Generate Skill

## Activation

When triggered, briefly describe:
- That you'll read raw-scan.md to understand the project structure
- You'll autonomously decide module boundaries using the configured granularity strategy
- Each module gets exactly **one README.md** in Recipe-First format (≤100 lines)
- You'll populate prospec/index.md (with the Progressive Knowledge Loading Strategy section) and _conventions.md

## 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` — if exists
2. [STABLE] Read `prospec/ai-knowledge/_module-readme-conventions.md` and `prospec/ai-knowledge/_diagram-conventions.md` — the canonical module-README structure and diagram rules to generate against (Step 4 generates directly against this canonical file — it is not restated here)
3. [STABLE] Read `prospec/CONSTITUTION.md` — if exists
4. [DYNAMIC] Ensure `prospec/ai-knowledge/raw-scan.md` is current, then read it — first run `prospec knowledge init --raw-scan-only` (deterministic, no LLM; creates it if absent) so READMEs generate against the real current structure. `module-map.yaml` must already exist (init bootstrap)
5. [DYNAMIC] Read `prospec/index.md` — if exists
6. [DYNAMIC] Read `.prospec.yaml` → check `knowledge.strategy` (auto|architecture|domain|package) and `knowledge.token_budget`

## Prerequisite

A full `prospec knowledge init` (bootstrap) must run first to produce `raw-scan.md`, `module-map.yaml`, and
scaffolding — there is no fallback ladder and no approximate working-tree scan. `module-map.yaml` comes only
from the full init, never `--raw-scan-only`, so a first-ever run needs it.

## 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`

`index.md`'s budget note must declare **all seven** — `knowledge-size` grades all seven — citing `.prospec.yaml` `knowledge.token_budget` as the source and `prospec check knowledge-size` as the enforcement, never an internal constant name.

## Core Workflow

### Step 1: Analyze Project Type

Identify project type from raw-scan.md:

| Indicator | CLI Tool | Backend API | SPA Frontend | Mobile App | Monorepo |
|-----------|----------|-------------|--------------|------------|----------|
| Entry | bin/, CLI entry | server.ts, app.ts | main.ts, App.tsx | App.tsx, main.dart | packages/ |
| Dirs | commands/, cli/ | routes/, controllers/ | components/, pages/ | screens/, navigation/ | packages/, apps/ |
| Framework | commander, yargs | express, fastify, django | react, vue, angular | react-native, flutter | turborepo, nx |
| Config | — | — | vite.config, next.config | app.json, pubspec.yaml | workspace config |

The table is a reference only — actual splitting should follow the project's real structure. A project may be a **hybrid** (e.g., full-stack with both backend API and frontend).

### Step 2: Determine Granularity Strategy

Read `.prospec.yaml` → `knowledge.strategy` and apply:

| Strategy | When to Use | Module = |
|----------|------------|----------|
| `architecture` | CLI tools, libraries with clear layer structure | Top-level `src/` directory (e.g., `commands/`, `lib/`, `services/`) |
| `domain` | Frontend apps, feature-organized projects | Business domain inferred from routes/components/pages naming |
| `package` | Monorepos, multi-package workspaces | Each workspace package (from pnpm-workspace.yaml, turbo.json, etc.) |
| `auto` (default) | Unknown or new projects | Try package → domain → architecture; pick first with ≥2 modules |

**After determining strategy, tell the user:**
> "Detected: [project type] ([framework]). Strategy: [strategy]. Modules: [count] ([list])."

### Step 3: Decide Module Boundaries

Apply the chosen strategy to split the project into modules. Guidelines:

- **Minimum**: 2 modules (even small projects have distinct responsibilities)
- **Maximum**: ~15 modules (more means too fine-grained; consider merging)
- **Merge**: Small directories with <3 files into their parent module
- **Split**: Large modules with >30 files into sub-domains if clear boundaries exist
- Each module must have a clear, distinct responsibility

**Revising `module-map.yaml` is yours to do.** Whatever is on disk may be a bootstrap draft. You are
the layer that can read the project. Judge what is on disk; do not assume it was decided.

One piece of evidence is raw-scan.md's **`## Directories Without Source Files`** section: the
topmost directories in which NO file passed that test, with file counts and extensions. Such a
directory can be a real module the heuristic cannot see. It is a partial view in both directions: a
listed directory may already BE a module — a curated `module-map.yaml` short-circuits detection
entirely. Read the Directory Tree and the current `module-map.yaml` alongside it.

- **Adding**: when a directory is this project's substance and `module-map.yaml` does not already
  cover it, propose it as a module. STOP. Ask the user to confirm the addition before writing. Check the existing
  `paths` first — a parent entry may already cover the directory the section lists.
- **Removing**: when an entry is really a documentation or asset directory, propose removing it
  under the same confirm-first discipline.
- **Leaving alone**: when the section is empty, when you judge the current map right, or when the
  user declines — `module-map.yaml` stays byte-identical. An empty section is not a reason to go
  looking: it means no directory was excluded for want of source files. Nothing on disk marks a map as bootstrap-written versus hand-curated, so
  never infer consent from the file itself: the user's confirmation is the only signal that a
  revision is wanted, and it is required every time.

Write revisions to `module-map.yaml` (the single source); `prospec/index.md`'s auto block is
regenerated from it in Step 5, never hand-edited. Same propose → confirm → write-back path the
`category` field already uses.

### Step 4: Create Module README.md (Recipe-First Format)

For each module, generate **exactly one file**: `prospec/ai-knowledge/modules/{module}/README.md`, following the **canonical Recipe-First structure** defined in `prospec/ai-knowledge/_module-readme-conventions.md` (loaded at Startup Loading — the single source for section order, the `# {ProperName}` title, each section's template, and the `prospec:auto`/`prospec:user` marker contract). Keep each section concise; total ≤100 lines.

**Key principles:**
- **Canonical template**: generate against `prospec/ai-knowledge/_module-readme-conventions.md` — it is the sole authority for README structure; do not restate the skeleton here.
- **Project Section Extensions**: the convention's preserved registry is the only authority for registered extension IDs, headings, purpose (the `Content` column — what the section is for), applicability, requiredness, visibility, and content format — not `.prospec.yaml` and not an inlined skill template. Emit a registered extension only with its section markers inside the README user block; preserve both marked extensions and freeform user notes when revising an existing README.
- **Format release**: follow the convention's dated format marker immediately after the summary and its fixed Core grammar; optional registered extensions do not change that format date.
- **No api-surface.md, dependencies.md, or patterns.md** — all information consolidated into README.md (or its sub-module files, see Step 4.5)
- **Modification Guide > API Reference** — tell agents HOW to change, not just WHAT exists
- **Ripple Effects** — prevent agents from making isolated changes that break other modules
- **Pitfalls** — capture tribal knowledge that prevents repeated mistakes

### Step 4.5: Extract Sub-Modules (only when a README would overflow)

If a module's README would exceed the ≤100 line / ≤2000 token budget even after reasonable trimming, AND it contains a **content-rich, functionally-independent** sub-area, extract that area into a sub-module file instead of trimming away useful detail (canonical rules: `prospec/ai-knowledge/_module-readme-conventions.md`).

- **Both conditions required** — overflow AND a self-contained sub-area (rich enough for its own Key Files / Public API / Pitfalls, understandable on its own). If only one holds, just trim.
- **Layout**: `prospec/ai-knowledge/modules/{module}/{sub-module}.md` — a sibling of `README.md`, kebab-case, same Recipe-First structure and same budget. A sub-module that still overflows is split again the same way.
- **Link back**: add a `## Sub-Modules` section to the main README listing `[Sub Name](./{sub-module}.md) — one-line`; move the extracted detail into the sub-module file (do not duplicate it back).
- **Not in `prospec/index.md`**: sub-modules are an L2 sub-layer discovered via the main README only — do NOT add them to `prospec/index.md` or `module-map.yaml` (keep L1 lean). If an area deserves an `prospec/index.md` entry, make it a real top-level module instead.

### Step 5: Populate prospec/index.md

> **Single source = `module-map.yaml`.** The curated columns — Keywords, Aliases, Rationale,
> Description, and Depends On (via `relationships.depends_on`) — are curated in
> `prospec/ai-knowledge/module-map.yaml`; `prospec/index.md`'s `prospec:auto` block is
> **generated** from it. Curate these fields in `module-map.yaml`, not by hand-editing the index
> table.

The `prospec:auto` block contains two auto-generated sections. Populate them within `prospec:auto-start/end` markers:

1. **Conventions**:
   - Scan the `prospec/ai-knowledge/` directory for `_*.md` files.
   - List them under **Core Conventions (L1)** if they are built-in core files (e.g. `_conventions.md`) or defined in `.prospec.yaml`'s `additional_core_conventions`.
   - List the rest under **Load-on-Demand Conventions**.

2. **Modules**: Fill the module table using the new format:

```
| Module | Keywords | Aliases | Status | Description | Rationale | Depends On |
```

- **Keywords**: exact identifiers an agent would search (file/symbol names, technical terms)
- **Aliases**: synonyms and natural-language terms that should still match this module — include terms in the project's artifact language (per the Constitution's Language Policy) and common synonyms (business logic, use case). Widens keyword-match coverage so L1 loading hits the right module without a semantic search.
- **Rationale**: Why this module exists as a separate unit (1 sentence)
- **Status**: Active / Deprecated / New

**Category derivation (optional, judgment-gated):**

When the modules fall into **≥2 meaningful domain categories** (e.g. by feature area):
- **Derive** each module's category from its paths, keywords, and purpose. Record it in
  `module-map.yaml` as an ordered `category: [primary, …secondary]` list — the single source of
  truth. Propose it. STOP. Ask the user to confirm the categories before writing them back; on later runs read category from
  `module-map.yaml` and never re-guess a module that already has one.
- **CLI Rendering**: The CLI will automatically render `### {Category}` grouped sub-tables in the index based on these values. Do not generate grouped tables manually.


### Step 6: Populate _conventions.md

Naming conventions, project-specific patterns, directory conventions, import ordering rules.

### Step 7: Quality Check

- Each module has clear responsibility boundaries
- No circular dependencies between modules
- **Each module README (and each sub-module) ≤ 100 lines** — if it overflows, first extract a content-rich, independent sub-area (Step 4.5); only trim when there is no such sub-area
- Every extracted sub-module is linked from its parent README's `## Sub-Modules` section and is NOT listed in `prospec/index.md`
- README contains all Recipe-First sections (Key Files, Public API, Dependencies, Modification Guide, Ripple Effects, Pitfalls)
- prospec/index.md has Aliases + Rationale columns
- **Each L1 file (prospec/index.md, each core convention) ≤ 2500 tokens per file** (estimate ~4 chars/token)
- All `prospec:user-start/end` content preserved, including marked extension sections and freeform user notes
- Strategy matches project structure (auto resolved correctly)

### Step 8: Constitution Emptiness Check

After Knowledge is generated, run `prospec check --json` and read its `constitution-severity` check.
If it reports a "no project-authored principles" finding — the Constitution holds only the
seeded example rules and the Language Policy — or is skipped because the Constitution declares none at all,
it is **substantively empty** — tell the user that `prospec-verify` and the Entry/Exit gates stay
no-ops until real principles exist, and point them to edit `prospec/CONSTITUTION.md`. Advisory — do not block.

## 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
- [ ] each module has exactly one Recipe-First README
- [ ] prospec/index.md has the module table + Progressive Knowledge Loading Strategy section
- [ ] each L1 file <= 2500 tokens
- [ ] >= 2 modules

### Failure Conditions
- ran without raw-scan.md
- produced api-surface.md / dependencies.md / patterns.md

### 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** start without raw-scan.md — Startup Loading runs `prospec knowledge init --raw-scan-only` to (re)generate it; a first-ever run needs the full `prospec knowledge init` (bootstrap) first
- **NEVER** create circular module dependencies — module dependency graph must be a DAG
- **NEVER** put all files in a single module — even small projects need 2-3 responsibility modules minimum
- **NEVER** ignore Tech Stack info from raw-scan.md — it affects module splitting strategy
- **NEVER** write outdated file paths in READMEs — all paths must come from raw-scan.md real data
- **NEVER** generate api-surface.md, dependencies.md, or patterns.md — all info goes in README.md only
- **NEVER** exceed 100 lines per module README or sub-module — when it overflows, extract an independent sub-area to `{module}/{sub-module}.md` (Step 4.5) before resorting to lossy trimming; agent uses L2 (source) for details
- **NEVER** list sub-modules in `prospec/index.md` or `module-map.yaml` — they are an L2 sub-layer reached only via the parent README's `## Sub-Modules` links
- **NEVER** duplicate source code in README — use function signatures and 1-line descriptions; the README is a map, not a copy
- **NEVER** use passive voice for confirmation wait points — always use an active imperative ("STOP. Ask the user...").

## Error Handling

| Scenario | Action |
|----------|--------|
| raw-scan.md stale or missing | Refresh via `prospec knowledge init --raw-scan-only`; `module-map.yaml` absent → full `prospec knowledge init` |
| raw-scan.md incomplete | List missing sections, suggest re-running `prospec knowledge init --raw-scan-only` (or full init) or manual completion |
| Module README already exists | Do not mechanically re-render it; preserve marked extension sections and freeform user notes, and migrate format only with consent |
| Strategy produces <2 modules | Fall back to `architecture` strategy |
| Module README exceeds 100 lines | If a content-rich, independent sub-area exists → extract a sub-module (Step 4.5) and link it; otherwise trim Key Files and Public API, keeping Modification Guide and Pitfalls intact |
| Ambiguous project type | Ask user to clarify, or treat as hybrid |