# Capy Knowledge Base Protocol

If `capy` MCP tools are not available in this session, skip all search and index steps below and proceed normally.

## Source Label Taxonomy

All plugin-managed labels use the `kk:` namespace prefix.

| Label                    | Contents                                                              |
| ------------------------ | --------------------------------------------------------------------- |
| `kk:arch-decisions`      | Architecture decisions, design rationale, trade-offs                  |
| `kk:review-findings`     | Code review patterns, recurring issues, anti-patterns                 |
| `kk:lang-idioms`         | Language best practices, idiomatic patterns from external sources     |
| `kk:project-conventions` | Discovered project patterns, naming conventions, structural decisions |
| `kk:test-patterns`       | Testing approaches, edge cases, test infrastructure decisions         |
| `kk:debug-context`       | Root causes, tricky bugs and their fixes, environment gotchas         |

## Search Conventions

- Use 2-4 specific terms per query — not vague keywords
- Always scope with `source` filter to relevant `kk:*` labels
- Use `source: "kk:"` only for broad cross-domain searches (e.g., CoVe verification)
- Default `limit: 3` per query unless more context is needed
- **Cold-start fallback:** If no results, proceed with standard guidelines — empty results are normal for new projects

## Index Conventions

- Only index non-obvious learnings not derivable from reading the code or git history
- Keep content concise — summarize the insight, don't dump raw output
- Always use a `kk:` prefixed label from the taxonomy above
- One concept per `capy_index` call — don't bundle unrelated learnings
- Skip indexing if the insight is already captured in design docs or CLAUDE.md

## Profile detection procedure

Single source of truth for computing the set of profiles active in the current context.
Consumed by six skills: `$kk:review-code`, `$kk:review-spec`, `$kk:design`, `$kk:implement`, `$kk:test`, and `$kk:document`.

Every profile under `klaude-plugin/profiles/<name>/` declares its own trigger rule in `DETECTION.md` using the mandatory three-section schema (`## Path signals`, `## Filename signals`, `## Content signals`).
The shared procedure below applies the same algorithm against every profile's declared values.

### Inputs per consuming skill

Not every consumer has a diff available. Use the input listed for your skill:

- **`$kk:review-code`** — git diff (staged, or an explicit commit range). Scope is
  the set of files the diff touches.
- **`$kk:review-spec`** — git diff when invoked standalone; the feature directory's
  full file list when invoked by `$kk:implement` (spec review runs over the whole
  feature, not just the current task's diff).
- **`$kk:test`** — git diff mid-feature, OR the feature directory's file list
  post-implementation.
- **`$kk:implement`** — the current sub-task's target file list, augmented by the
  diff accumulated so far in the feature.
- **`$kk:design`** — **no file list available** (implementation does not yet exist).
  Detection uses a user-declared or keyword-inferred signal instead; see
  [The `$kk:design` interaction pattern](#the-design-interaction-pattern) below.
- **`$kk:document`** — feature directory's current file list; diff optional.

### The `$kk:design` interaction pattern

The design phase runs before any code exists, so file-based detection is impossible. Detection uses idea-prose keyword matching against tokens declared in each profile's `DETECTION.md`.

**Algorithm:**

1. **Collect tokens.** Iterate §Known profiles. For each `<name>`, `Read` `../../profiles/<name>/DETECTION.md`. If the file has no `## Design signals` section, skip — that profile does not participate in design-phase detection. Otherwise, parse `display_name` and `tokens` from the section.
2. **Build union.** Collect all declared tokens into a single set, each tagged by its source profile name and `display_name`.
3. **Match.** Check the idea prose against the union. Matching is case-insensitive, whole-word (so `pod` in "podcast" does not fire).
4. **Confirm.** On match, surface a confirmation prompt per matched profile:
   *"This appears to be a {display_name} feature. Activate the {profile_name} profile?"* — let the user confirm yes/no. When multiple profiles match, confirm each independently.
5. **Fallback.** If no token matches but the idea is **ambiguous** — names infrastructure, deployment, runtime, or platform concerns without naming a specific technology (e.g., _"add a caching layer for the service"_, _"build a CI pipeline"_, _"deploy to production"_); or includes overloaded tokens that collide across domains — build the fallback prompt dynamically from all profiles that declare `## Design signals`:
   *"Does this feature involve {display_name_1, display_name_2, ...}? If yes, which?"*

Confirmation is required — the $kk:design skill never auto-activates a profile silently. The narrow per-profile token sets avoid noisy false positives from tokens that overload across domains.

Once activated, subsequent design-phase steps treat the profile as active in the same record shape produced by file-based detection (see §Output shape).

### Known profiles

This is the authoritative enumeration of profile `<name>`s — do NOT try discover profiles via any other means.
An explicit list is boring, deterministic, and unambiguous; runtime filesystem enumeration against the plugin tree has proven unreliable.

- `go`
- `python`
- `java`
- `js_ts`
- `kotlin`
- `k8s`
- `k8s-operator`
- `skill-md`

### Algorithm

This procedure reads files under the plugin root. The main agent resolves the plugin root from its shell variable `$TOOLBOX_PLUGIN_ROOT`; a Read-only sub-agent uses the absolute plugin-root path injected into its prompt under `## Plugin Root` (see its agent definition). Substitute that resolved path for the plugin-root prefix in every `…/profiles/…` read below.

1. **Iterate profiles.** For each §Known profiles `<name>`:
   1. Use the `Read` tool on `../../profiles/<name>/DETECTION.md`.
   2. If `Read` fails with ENOENT (profile name in list but directory missing — a stale list entry), skip silently and move on.
   3. If `Read` succeeds, parse the declared `## Path signals`, `## Filename signals`, and `## Content signals` sections.

2. **Evaluate in cost order.** For each input file, check signals in this order: path → filename → content. Cheapest first.
3. **Apply the authority rule.** A file activates the profile only if a **filename signal** OR **content signal** matches.
   A path-only match does NOT activate. Paths are a pre-filter that promotes files to "candidates"; authoritative activation requires filename or content confirmation.
   A file that matches NO path signal is still evaluated against filename and content signals — path pre-filtering is a cost hint, not a gate.
   (Otherwise a `Chart.yaml` at a non-standard path would be missed.)
4. **Bound content inspection.** Read at most ~16 KB per file when evaluating content signals.
   Multi-document YAML is inspected per `---`-separated block — a file may have five blocks, and only the third need match for the file to activate the profile.
5. **Collect records.** Accumulate one record per matched profile with the triggering files and the signal descriptions that fired.

### Tool choice

- Single file at `../../…` → `Read`. This is what the algorithm uses.
- Enumeration across profiles → iterate the §Known profiles list, `Read` each. Never `Glob` (cwd-scoped, misses outside-cwd paths).

### Two dimensions: cost vs authority

Signals live on two axes that point in different directions. Keep them separate in your mental model:

- **Evaluation cost** (cheapest first): path < filename < content.
  Path globs touch only the path string;
  filename matches are exact string compares;
  content inspection opens the file.
- **Authority** (most authoritative first): filename ≈ content > path.
  A filename or content match activates the profile; a path-only match does not.
  Filename and content are equally authoritative, but filename resolves first at runtime — a filename match short-circuits content inspection for that file.

Evaluating cheapest-first optimizes work. Applying authority correctly prevents false positives from incidental path matches — a stray `manifests/` directory in a Go project does not make the project Kubernetes.

### Plugin-root resolution failure

If every `Read` attempt in Algorithm step 1 fails — i.e., the plugin root could not be resolved (the variable is unset for the main agent, or no `## Plugin Root` path was provided to a sub-agent) or the paths do not exist — the procedure cannot continue.

On that failure:

1. Emit an actionable error pointing to `CLAUDE.md` §Profile Conventions.
2. Return an empty result set so the calling skill falls back to generic guidance rather than panicking.
3. Do not retry; do not silently guess a path.

Consumers inherit this check by invoking the shared procedure — no skill re-implements it.

### Output shape

A list of records, one per matched profile:

```
[
  {
    profile: "<name>",                     // directory name under profiles/
    triggered_by: [
      "filename: Chart.yaml",              // signal type + matched value
      "content: apiVersion+kind in block 2"
    ],
    files: [
      "path/to/file1.yaml",
      "path/to/file2.yaml"
    ]
  },
  ...
]
```

Field semantics:

- `profile` — the directory name under `profiles/` (e.g., `go`, `python`, `k8s`).
  Used downstream to resolve `profiles/<profile>/<phase>/index.md`,
  where `<phase>` is the profile phase subdirectory named identically to the calling skill:
  `review-code/`, `review-spec/`, `design/`, `implement/`, `test/`, or `document/`.
- `triggered_by` — which signal type fired and the specific value that matched.
  For debugging and for explaining detection to the user; never used as the key for profile lookup.
- `files` — the subset of input files that activated this profile.
  Skills use this to scope behavior (e.g., `helm lint` runs only on files triggered under Helm filename signals, not on every YAML in the diff).

When no profile matches, return the empty list `[]`. The caller falls back to generic guidance, identical to today's "no language detected" path.

---
name: document
description: |
  After implementing a new feature or fixing a bug, make sure to document the changes.
  Use when writing documentation, after finishing the implementation phase for a feature or a bug-fix.
---
<!-- codex: tool-name mapping applied. See .codex/scripts/session-start.sh -->

# Documentation Process

## Conventions

- **Read capy knowledge base conventions** at [shared-capy-knowledge-protocol.md](shared-capy-knowledge-protocol.md).
- **Read profile detection** at [shared-profile-detection.md](shared-profile-detection.md). When an active profile contributes a `document/` subdirectory (e.g., `../../profiles/k8s/document/`), its `index.md` lists a doc rubric — required topics the documentation for that artifact type must cover. See the Workflow below for the load order.

## Workflow

**Mandatory order — instructions before action.** The flow below is strictly sequential. Do not read feature-tree content, write, or edit documentation files until profile detection has completed and all resolved profile content is in context.

1. **Minimal-scope listing.** List the feature directory (filenames and metadata only — no file-content reads). This is the input profile detection needs, and nothing more; content-level reading happens after profile content is loaded.
2. **Detect active profiles.** Run the `shared-profile-detection.md` procedure against the filename list from Step 1.
3. **Load profile content.** For each active profile that contributes a `document/` subdirectory, load `../../profiles/<name>/document/index.md` and read its always-load + any matching conditional content. The rubric named there specifies topics the documentation must cover for that profile's artifacts.
4. **Read the feature-tree content** the documentation will cover. This is the first step that touches subject-matter content; the profile rubric is now loaded and frames what to look for.
5. **Apply the doc guidelines below.** Write or update documentation applying the rubric's required topics where applicable.

## Guidelines

1. **Discover the project's documentation structure.** List top-level doc directories and doc-related files at the repo root (e.g., `docs/`, `README.md`, `ARCHITECTURE.md`, `CONTRIBUTING.md`). Scan for architecture guides, testing guides, API docs, user guides, and contributing docs — common locations include `docs/contributing/architecture.md`, `docs/contributing/testing.md`, but every project organizes differently. Update whichever docs are relevant to the change — don't limit yourself to a fixed set of paths.
2. If the code change included prior decision-making out of several alternatives, document an ADR at `/docs/adr` for any non-trivial/non-obvious decisions that should be preserved.
3. **Profile-aware rubric.** For each active profile, apply the doc rubric its `document/index.md` specifies (loaded in Step 3 of the Workflow). Each required topic must be addressed in one of three ways: (a) write the topic if the feature touches it, (b) state `N/A — <reason>` in a single line if the feature does not touch the topic, or (c) cite the inherited source explicitly if the feature assumes the topic but inherits it from elsewhere (e.g., NetworkPolicy defined in a platform repo). Silent omission is the failure mode — an explicit `N/A` communicates consideration; an absent heading communicates nothing.

**Capy search:** Before writing docs, search `kk:arch-decisions` and `kk:project-conventions` for decisions that should be reflected in documentation — decisions not obvious from code alone.