git:20260307.5f24766 to git:20260310.cbfa9e5

27 added, 52 removed. Audit B to A.

# Commonplace

- A framework for building agent-operated knowledge bases. This repo contains the methodology, type definitions, writing conventions, skill templates, and scripts that get installed into projects.

+ A framework for building agent-operated knowledge bases. This repo contains the methodology, type definitions, writing conventions, instructions and skills, and scripts that get installed into projects.

The commonplace repo is itself a knowledge base — it uses its own knowledge system to document the methodology for building knowledge bases. There is no separation between "user content" and "methodology" here; the methodology IS the content.

## Fast Path (Default)

If you need to act quickly and are unsure which specialized path applies, do this:

1. Write a `note` in `kb/notes/` (default type).

- 2. Follow the checklist/template in `kb/WRITING.md`.

+ 2. Follow the checklist/template in `kb/instructions/WRITING.md`.

3. Connect the note to related notes and at least one index (`/connect` or manual links with explicit relationship semantics).

4. Run `/validate` to check structure, frontmatter, and links.

Use specialized types only when the routing table explicitly points to one.

## Knowledge System

### Routing Table

| What you're doing | Where it goes | Type guidance |

|---|---|---|

- | Design note or insight | `kb/notes/` | Default `note` type (template in `kb/WRITING.md`) |

+ | Design note or insight | `kb/notes/` | Default `note` type (template in `kb/instructions/WRITING.md`) |

| Structured argument | `kb/notes/` | Read `kb/notes/types/structured-claim.md` — needs Evidence/Reasoning/Caveats |

| Architecture decision | `kb/notes/adr/` | Read `kb/notes/types/adr.md` — needs Context/Decision/Consequences |

| Related system review | `kb/notes/related-systems/` | Read `kb/notes/types/related-system.md` |

| Improvement opportunity noticed during traversal | `kb/log.md` | Append one line — don't fix it now, don't context-switch |

| External source snapshot | `kb/sources/` | Use `/snapshot-web` skill |

| Source analysis | `kb/sources/` | Use `/ingest` skill — produces `.ingest.md` |

| Task | `kb/tasks/backlog/` or `kb/tasks/active/` | Status encoded by directory, not frontmatter |

- | Scenario cost evaluation | `kb/scenarios/` | Read `kb/scenarios/types/scenario.md` |

+ | Reusable procedure | `kb/instructions/` | Imperative steps, frontloaded, minimal reasoning |

| Area index (curated) | `kb/notes/` | Read `kb/notes/types/index.md` — entries MUST have context phrases |

### Content Workflow

1. **Search first** — find related notes before writing. This is especially important in this repo where the related notes ARE the methodology the new note builds on.

- 2. **Read WRITING.md** — `kb/WRITING.md` has the full checklist (title-as-claim, description quality, index membership, composability) and templates for `note` and `structured-claim`. It's the authority on how to write. For most notes, this is all you need.

- 3. **Read the directory type** — only if the routing table points to a specific type template (adr, index, related-system, scenario). Skip this step for plain notes.

+ 2. **Read WRITING.md** — `kb/instructions/WRITING.md` has the full checklist (title-as-claim, description quality, index membership, composability) and templates for `note` and `structured-claim`. It's the authority on how to write. For most notes, this is all you need.

+ 3. **Read the directory type** — only if the routing table points to a specific type template (adr, index, related-system). Skip this step for plain notes.

4. **Write** the note.

5. **Connect** — link the new note from related notes and area indexes. Use `/connect` or do it manually. Don't skip this step — an unconnected note is invisible to future search.

### Search Patterns (Core)

```bash

# Find notes by keyword

- rg "keyword" kb/notes/ --glob "*.md"

+ rg "keyword" kb/notes/ kb/instructions/ --glob "*.md"

# Find notes by description

- rg "^description:" kb/notes/ --glob "*.md"

+ rg "^description:" kb/notes/ kb/instructions/ --glob "*.md"

# Find notes by type

- rg "^type: structured-claim" kb/notes/ --glob "*.md"

+ rg "^type: structured-claim" kb/notes/ kb/instructions/ --glob "*.md"

# Find notes by area

- rg "^areas:.*kb-design" kb/notes/ --glob "*.md"

+ rg "^areas:.*kb-design" kb/notes/ kb/instructions/ --glob "*.md"

```

Use `/validate` for specialized audits and consistency checks.

+ ### Escalation Boundaries

+ Stop and load deeper guidance when any of these are true:

+ - You cannot map the artifact cleanly through the routing table -> read `kb/instructions/WRITING.md` before creating or moving files.

+ - You are editing notes in a directory with a local `types/` template -> read that template first.

+ - You touch `kb/sources/` content and there is no corresponding `.ingest.md` -> run `/ingest` (or ask the user which ingest workflow to use) instead of improvising classification.

+ - The task is an externally triggered operation class (maintenance sweep, audit, bulk refactor) -> use the operations catalogue/instructions path, not the default AGENTS flow.

+ This file is a control-plane router. It does not inventory capabilities; harness-injected skills provide capability discovery.

### Key Indexes

- `kb/notes/kb-design.md` — main index: foundations, observations, decisions, gaps

- `kb/notes/links.md` — linking methodology: semantics, navigation, contracts

- `kb/notes/related-systems/related-systems-index.md` — external system comparisons

- `kb/notes/index.md` — auto-generated directory listing (rebuild with `scripts/generate_notes_index.py`)

- `kb/sources/index.md` — auto-generated source listing

- ## Types Architecture

- Types use progressive disclosure: global types cover most work; directory-scoped types load on demand only when the routing table points to them.

- ### Global types (`types/`) — always available

- - `text` — no frontmatter, no requirements. The starting point for raw captures.

- - `note` — has frontmatter with description, status, traits, areas. Templates inlined in `kb/WRITING.md`. **This is the default type for most writing — don't read directory types unless you need a specialized structure.**

- ### Directory-scoped types — load on demand

- Each collection has a `types/` subdirectory with templates that extend `note`. Read these only when the routing table directs you to a specific type:

- - `kb/notes/types/` — `structured-claim`, `adr`, `index`, `related-system`

- - `kb/sources/types/` — `source-review`

- - `kb/tasks/types/` — `task-active`, `task-backlog`, `task-recurring` (no frontmatter — status encoded by directory)

- - `kb/scenarios/types/` — `scenario`

- The base type distinction: **no frontmatter** = `text` (no requirements); **has frontmatter** = `note` or more specific type (full quality checks apply, inheriting from global `types/note.md`).

- ## Skills

- Skills live in `skills/` and are symlinked into `.claude/skills/`. In installed projects, the symlinks point from the project's `.claude/skills/` into `commonplace/skills/`.

- | Skill | Purpose |

- |---|---|

- | `/validate` | Schema validation — checks frontmatter, descriptions, types, links, structure |

- | `/connect` | Find connections between notes, update indexes, weave knowledge graph |

- | `/convert` | Convert notes between types (text→note, note→structured-claim) |

- | `/ingest` | Ingest external source: snapshot → connect → classify → analyse |

- | `/snapshot-web` | Capture URL to `kb/sources/` (web, GitHub, X/Twitter, PDF) |

- | `/evaluate-scenarios` | Measure scenario costs — hops and instruction bytes from source files |

- ## Scripts

- | Script | Purpose |

- |---|---|

- | `scripts/generate_notes_index.py` | Regenerate directory index for a collection |

- | `scripts/sync_topic_links.py` | Sync `Topics:` footer from `areas:` frontmatter |

- | `scripts/github_snapshot.py` | Snapshot GitHub issues/PRs |

- | `scripts/x_snapshot.py` | Snapshot X/Twitter posts |

+ ## Type Routing

- Run scripts with `uv run scripts/<script>`.

+ - `text` = no frontmatter (raw capture).

+ - `note` = has frontmatter (default structured writing type).

+ - For specialized structures, load the directory-local type templates only when the routing table points there:

+ `kb/notes/types/`, `kb/sources/types/`, `kb/tasks/types/`.

+ - `kb/instructions/WRITING.md` is the authority for note-writing checklist and the default templates.

## Git

- **Never `git add -A`** — review `git status` and stage specific files.

- **Prefer atomic stage+commit** — combine staging and committing in one command (`git add <files> && git commit -m "..."`). Leaving files staged without committing risks another agent's commit sweeping in unrelated changes.

## Conventions

- **Links**: Standard markdown links, not wiki-links. Relative paths from source file. `[title](./title.md)`

- **Link semantics**: Every link must articulate the relationship (extends, grounds, contradicts, enables, exemplifies). "Related" is not a relationship.

- **Filenames**: Lowercase, hyphens for spaces, `.md` extension. Derived from the `# Title` heading.

- **Frontmatter**: YAML between `---` delimiters. `description` is the most important field — it's a retrieval filter, not a summary.

- **No wiki-links**: This KB uses standard markdown links exclusively.