Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions .claude/skills/llp-create/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Invoke as `/llp-create <title>` with an optional title, or `/llp-create` and the

## Ground rules

- LLP documents live in `llp/` (flat or grouped into subdirectories see LLP 0000 for filesystem organization rules).
- LLP documents live in `llp/` (flat or grouped into subdirectories: see LLP 0000 for filesystem organization rules).
- Filenames follow `NNNN-slug.type.md` where `NNNN` is zero-padded four digits, `slug` is a lowercase kebab-case identifier, and `type` is the lowercased document type.
- Numbers are globally unique across the entire `llp/` tree, including subdirectories and `llp/tombstones/`. Never reuse a number that has ever been assigned.
- Standard types (LLP 0000 §Types): `rfc`, `spec`, `decision`, `plan`, `explainer`, `principle`, `guide`, `issue`, `research`. Projects may define additional types; check the project's root LLP for any local conventions.
Expand All @@ -29,8 +29,8 @@ If another LLP tree exists in a non-standard location (some projects use `docs/s

Required to produce a useful scaffold:

- **Title** short, sentence case. If not provided by the slash command argument, ask.
- **Type** which of the standard types fits best. If the user didn't specify, propose one based on the title and current conversation context, then confirm. Common cues:
- **Title**: short, sentence case. If not provided by the slash command argument, ask.
- **Type**, which of the standard types fits best. If the user didn't specify, propose one based on the title and current conversation context, then confirm. Common cues:
- "How should we..." / "Proposal to..." → `rfc`
- "What are the requirements..." / "Specification of..." → `spec`
- "We decided..." / "Chose X over Y" → `decision`
Expand All @@ -40,16 +40,16 @@ Required to produce a useful scaffold:
- "How to use..." / "Workflow for..." → `guide`
- "Bug in..." / "Problem with..." → `issue`
- "Analysis of..." / "Findings from..." → `research`
- **Systems** one or more system tags relevant to this LLP. Ask if unclear.
- **Related** existing LLPs worth reading alongside this one. Ask the user or propose based on topic overlap.
- **Systems**: one or more system tags relevant to this LLP. Ask if unclear.
- **Related**: existing LLPs worth reading alongside this one. Ask the user or propose based on topic overlap.

### 3. Generate the slug from the title

- Lowercase
- Replace any character that is not `a-z0-9` with `-`
- Collapse repeated `-` into a single `-`
- Trim leading and trailing `-`
- Keep it short aim for fewer than 6 words. If the title is long, truncate the slug after the meaningful words.
- Keep it short: aim for fewer than 6 words. If the title is long, truncate the slug after the meaningful words.

Example: `"Token rotation and session management"` → `token-rotation-and-session-management`. If that feels long, shorten to `token-rotation`.

Expand Down Expand Up @@ -79,7 +79,7 @@ Why does this exist? What problem does it solve?

## Design

The body of the document. Structure this however the type and topic demand RFCs usually have a Design section with sub-headings; Decisions have Context / Options / Decision / Consequences; Plans have phase breakdowns; etc.
The body of the document. Structure this however the type and topic demand - RFCs usually have a Design section with sub-headings; Decisions have Context / Options / Decision / Consequences; Plans have phase breakdowns; etc.

## Open questions

Expand Down
22 changes: 11 additions & 11 deletions .claude/skills/llp-grill/DECISION-DISPOSITION.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,18 +26,18 @@ Does this decision change how the system is or should be built/understood?
→ Is it a genuine, non-obvious decision a future agent could get wrong?
├─ YES → Create a new LLP (next number, NNNN-slug.type.md, full header).
│ Choose Type deliberately:
│ Decision a settled choice + its rationale (ADR-like)
│ Spec normative "must/must not" the code follows
│ Principle an "always/never" that guides many decisions
│ Plan execution steps (often tombstoned once done)
│ Decision - a settled choice + its rationale (ADR-like)
│ Spec - normative "must/must not" the code follows
│ Principle - an "always/never" that guides many decisions
│ Plan - execution steps (often tombstoned once done)
│ Tag **Systems:** with the existing vocabulary (or extend it
│ and update LLP 0000's map).
└─ NO → It's obvious from the code and filename. Write nothing.
```

## The capture bar (lower than ADRs, but not zero)

LLP documents are *living* editable, supersede-able, deletable so you are
LLP documents are *living* (editable, supersede-able, deletable), so you are
not making a permanent commitment the way an append-only ADR is. That lowers the
cost of capturing, but the **value** test is the same one from LLP 0000:

Expand All @@ -46,20 +46,20 @@ cost of capturing, but the **value** test is the same one from LLP 0000:

Strong candidates:

- **Cross-cutting invariants** "sources never see sinks", "one source, one
- **Cross-cutting invariants**: "sources never see sinks", "one source, one
table". Code that violates these looks locally fine.
- **Deliberate deviations from the obvious path** anything where a reasonable
- **Deliberate deviations from the obvious path**: anything where a reasonable
agent would assume the opposite and "fix" it.
- **Boundary and ownership decisions** who owns this data/table/capability;
- **Boundary and ownership decisions**, who owns this data/table/capability;
the explicit no-s are as valuable as the yes-s.
- **Constraints not visible in code** compliance, latency budgets, a contract
- **Constraints not visible in code**: compliance, latency budgets, a contract
with an upstream the code can't show.

Skip:

- The obvious ("we use the standard library here").
- Volatile, still-being-prototyped code wait until the design stabilises.
- Restating what an existing LLP already says link to it instead.
- Volatile, still-being-prototyped code: wait until the design stabilises.
- Restating what an existing LLP already says: link to it instead.

## After disposition

Expand Down
18 changes: 9 additions & 9 deletions .claude/skills/llp-grill/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,25 +22,25 @@ This is the LLP-aware variant of `grill-with-docs`: the documents you challenge
Before grilling, build a map of the existing design rationale.

- Find the `llp/` tree. Read the root document (`LLP 0000`, `**Role:** Root`) for the project overview, the **subsystem map**, and the **Systems vocabulary**.
- Identify the Active LLPs whose `**Systems:**` tags overlap what the plan touches. Read them these are the decisions the plan has to live with or consciously overturn.
- Note status. Only **Active** LLPs are current guidance. If the plan revives something **Superseded** or **Tombstoned** (under `llp/tombstones/`), surface that explicitly it may be a sign the decision was already considered and rejected.
- Identify the Active LLPs whose `**Systems:**` tags overlap what the plan touches. Read them: these are the decisions the plan has to live with or consciously overturn.
- Note status. Only **Active** LLPs are current guidance. If the plan revives something **Superseded** or **Tombstoned** (under `llp/tombstones/`), surface that explicitly: it may be a sign the decision was already considered and rejected.
- If the project also has a `CONTEXT.md` glossary, treat it as the term authority alongside the `Systems` vocabulary.

If there is no `llp/` tree yet, this is the wrong skill point the user at `/llp-init` or `/llp-init-retrofit` first, then grill.
If there is no `llp/` tree yet, this is the wrong skill: point the user at `/llp-init` or `/llp-init-retrofit` first, then grill.

## During the session

### Challenge against existing decisions

When the plan contradicts an Active LLP a Spec's "must", a Decision's chosen option, a Principle's "always/never" call it out immediately and force the choice:
When the plan contradicts an Active LLP (a Spec's "must", a Decision's chosen option, a Principle's "always/never"), call it out immediately and force the choice:

> "LLP 0014#queryable-sinks says queryability is a property of the writer/destination pair, but your plan assumes any S3 sink is queryable. Either the plan changes, or LLP 0014 does which?"
> "LLP 0014#queryable-sinks says queryability is a property of the writer/destination pair, but your plan assumes any S3 sink is queryable. Either the plan changes, or LLP 0014 does, which?"

Cite the LLP number and section anchor so the conflict is precise. A plan that silently diverges from an Active LLP is the exact failure LLP exists to prevent: the next agent reads the LLP, writes code to it, and contradicts your plan.

### Sharpen terminology against the Systems vocabulary

When the plan uses a term that conflicts with the project's established language, stop and resolve it. Keep `Systems` names consistent don't let the plan introduce `Auth` when the corpus says `Authentication`, or coin a new system name for something an existing tag already covers. If a new `System` is genuinely needed, name it and note that `LLP 0000`'s vocabulary must be updated.
When the plan uses a term that conflicts with the project's established language, stop and resolve it. Keep `Systems` names consistent: don't let the plan introduce `Auth` when the corpus says `Authentication`, or coin a new system name for something an existing tag already covers. If a new `System` is genuinely needed, name it and note that `LLP 0000`'s vocabulary must be updated.

### Discuss concrete scenarios

Expand All @@ -52,17 +52,17 @@ When the user states how something works, check whether the code agrees. If the

> "`src/sinks/driver.js` is annotated `@ref LLP 0014#export-contract [implements]`, which says sinks ack per-batch. Your plan acks per-row, which breaks the referenced contract."

### Capture decisions inline into the LLP corpus
### Capture decisions inline: into the LLP corpus

When a decision crystallises, dispose of it **right there**. Don't batch. Unlike ADRs, LLP documents are *living* you edit, supersede, and delete freely so the bar to capture is lower, but the discipline is to put each decision in the right place. Use the disposition tree in [DECISION-DISPOSITION.md](./DECISION-DISPOSITION.md):
When a decision crystallises, dispose of it **right there**. Don't batch. Unlike ADRs, LLP documents are *living* (you edit, supersede, and delete freely), so the bar to capture is lower, but the discipline is to put each decision in the right place. Use the disposition tree in [DECISION-DISPOSITION.md](./DECISION-DISPOSITION.md):

- **Refines an existing Active LLP** → edit that LLP in place.
- **A new non-obvious decision** → create a new LLP. Use the next available number and the `NNNN-slug.type.md` convention with a full metadata header (follow `/llp-create`). Pick the `Type` deliberately (Decision vs Spec vs Principle).
- **Overrides an Active LLP** → update the LLP to the new decision. If the old framing still has migration value, mark it `Superseded` and write the replacement; otherwise just edit.
- **Retires guidance entirely** → move the LLP to `llp/tombstones/` with `**Status:** Tombstoned`.
- **An implementation constraint, not a standalone decision** → don't write an LLP. Note it as an `@ref` to add when the code lands, pointing at the LLP section that explains the constraint.

Keep each captured LLP edit scoped to the decision stable heading anchors, tight prose, no implementation dumps.
Keep each captured LLP edit scoped to the decision: stable heading anchors, tight prose, no implementation dumps.

### Keep the corpus honest

Expand Down
26 changes: 13 additions & 13 deletions .claude/skills/llp-list/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,11 @@ Use this skill when the user wants to see what LLPs exist in the repo, or filter

Invoke as:

- `/llp-list` show all LLPs grouped by status
- `/llp-list <status>` show only LLPs with that status (e.g., `/llp-list draft`, `/llp-list active`)
- `/llp-list type=<type>` show only LLPs of a given type (e.g., `/llp-list type=rfc`)
- `/llp-list system=<system>` show only LLPs tagged with a given system
- `/llp-list author=<name>` show LLPs by a specific author
- `/llp-list`: show all LLPs grouped by status
- `/llp-list <status>`: show only LLPs with that status (e.g., `/llp-list draft`, `/llp-list active`)
- `/llp-list type=<type>`: show only LLPs of a given type (e.g., `/llp-list type=rfc`)
- `/llp-list system=<system>`: show only LLPs tagged with a given system
- `/llp-list author=<name>`: show LLPs by a specific author

Filters can combine: `/llp-list draft type=rfc system=auth`.

Expand Down Expand Up @@ -51,10 +51,10 @@ Normalize values:

If the user specified filters, remove LLPs that don't match. Supported filters:

- Status case-insensitive exact match after normalization
- Type case-insensitive exact match
- System case-insensitive substring match against the Systems list
- Author case-insensitive substring match against the Author field
- Status: case-insensitive exact match after normalization
- Type: case-insensitive exact match
- System: case-insensitive substring match against the Systems list
- Author: case-insensitive substring match against the Author field

If no filter is provided, show everything.

Expand Down Expand Up @@ -116,9 +116,9 @@ Or for filtered results:

By default, render as plain text. Support format flags:

- `/llp-list --format=json` emit a JSON array of LLP metadata for programmatic use
- `/llp-list --format=markdown` emit a markdown-formatted list, suitable for pasting into another document
- `/llp-list --format=table` emit a markdown table with Number / Title / Type / Status / Systems columns
- `/llp-list --format=json`: emit a JSON array of LLP metadata for programmatic use
- `/llp-list --format=markdown`: emit a markdown-formatted list, suitable for pasting into another document
- `/llp-list --format=table`: emit a markdown table with Number / Title / Type / Status / Systems columns

## Edge cases

Expand All @@ -129,5 +129,5 @@ By default, render as plain text. Support format flags:
## Scope limits

- Do not create, modify, or delete LLPs. This skill is read-only.
- Do not interpret LLP content just metadata. For content analysis, use `/llp-search` or `/llp-review`.
- Do not interpret LLP content: just metadata. For content analysis, use `/llp-search` or `/llp-review`.
- Do not follow cross-references (`Related:` fields). For cross-reference traversal, use `/llp-related`.
Loading
Loading