phronesis v0.3.0: port the four known skills from vibe-wiki - five bundled total

- fiona 2.2.0 (productivity) with its support files (llm-wiki-mod.md, markdown_rules.md)
- memory 1.0.1 (productivity) with MEMORIES.md template; CRLF converted to LF
- sectionize-markdown 1.2.0 (documentation); category added, minor bump
- specification-writer 1.1.0 (documentation); category added, minor bump
- autotest markdown check: md025 front_matter_title set never-matching, so a
  front-matter 'title' key is not an implicit second h1 (SPEC item 9.6)
- README skills table lists all five; all 7 autotest checks green

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
nvaldez
2026-11-19 10:20:04 +01:00
parent 196df53a9b
commit b0f07593b5
10 changed files with 3526 additions and 1 deletions
+6 -1
View File
@@ -62,7 +62,11 @@ phronesis/
| Skill | Version | Category | Purpose |
| --- | --- | --- | --- |
| [fiona](./skill/fiona/SKILL.md) | 2.2.0 | productivity | Operate an llm-wiki with the fiona-assistant CLI |
| [memory](./skill/memory/SKILL.md) | 1.0.1 | productivity | Give a skill its own MEMORIES.md beside its SKILL.md |
| [python-tdd](./skill/python-tdd/SKILL.md) | 1.2.0 | development | Minimalist TDD architect for Python work |
| [sectionize-markdown](./skill/sectionize-markdown/SKILL.md) | 1.2.0 | documentation | Number headings and list items so each rule can be cited |
| [specification-writer](./skill/specification-writer/SKILL.md) | 1.1.0 | documentation | Write structured, maintainable SPEC.md files |
## Checks
@@ -77,7 +81,8 @@ phronesis/
matches the directory, `version` is `x.y.z`, `category` is kebab
- **markdown** — markdownlint on every `.md` file, via `pymarkdownlnt`
with front-matter support; `md013` (line length) and `md033` (inline
HTML) are ignored
HTML) are ignored, and md025 treats front-matter `title` keys as
headings off, so skills with a `title` plus one `#` stay clean
- **pytest** — the suite in `test/` with 75 percent coverage floor
Run all checks:
+4
View File
@@ -271,6 +271,10 @@ python-tdd 1.2.0 development
- **9.5** `requirements.txt` pins the check dependencies and the test
dependencies; the runtime dependencies live in `pyproject.toml`
(SPEC item 10.2).
- **9.6** The markdown check configures md025's `front_matter_title`
search with a pattern that never matches, so a `title` key in
skill front matter is not an implicit second top-level heading;
a genuine duplicate h1 still fails the check.
## 10. Packaging
+2
View File
@@ -152,6 +152,8 @@ def check_markdown(paths: list[pathlib.Path]) -> int:
errors = 0
for path in paths:
api = PyMarkdownApi().enable_extension_by_identifier("front-matter")
# a 'title' key in front matter is not an implicit second h1 (SPEC item 9.6)
api.set_string_property("plugins.md025.front_matter_title", "^$")
for failure in api.scan_path(str(path)).scan_failures:
if failure.rule_id.lower() in MARKDOWN_IGNORE:
continue
+1187
View File
File diff suppressed because it is too large Load Diff
+144
View File
@@ -0,0 +1,144 @@
---
name: llm-wiki-mod
title: LLM Wiki Pattern
version: 1.4.1
updated: 2026-10-06
type: concept
tags: [wiki, schema]
---
# LLM Wiki
A persistent knowledge base of interlinked markdown. The pattern
comes from
[Andrej Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).
Page rules are in [schema](../../../wiki/schema.md). Commands and
the edit loop are in the [Fiona skill](./SKILL.md).
- [1. Core idea](#1-core-idea)
- [2. Layers](#2-layers)
- [3. Operations](#3-operations)
- [4. Index and log](#4-index-and-log)
- [5. Page rules](#5-page-rules)
- [6. Why this works](#6-why-this-works)
- [7. Scope](#7-scope)
## 1. Core idea
Sources are read once and compiled into wiki pages. Later questions
use those pages. Cross-references, contradictions, and synthesis
stay in the files. Each new source and each filed answer adds to
that store.
The human curates sources and asks the questions. The agent writes
the pages, updates cross-references, and keeps the bookkeeping.
## 2. Layers
Three layers. The directory tree in
[schema](../../../wiki/schema.md) is the map.
### 2.1. Raw sources
`raw/` is the archive. The agent adds new sources there and never
edits, moves, or deletes one already archived.
`ingest/` is the drop zone for files that still need parsing.
`personal/` holds user notes and is read-only, including the
directory itself.
### 2.2. The wiki
`wiki/` is agent-owned markdown. Synthesized pages go in
`concepts/`, `entities/`, `comparisons/`, and `queries/`. Source
summaries that back those pages go in `sources/`. The agent creates
pages, revises them when a new source arrives, and keeps links
consistent.
### 2.3. The schema
[schema](../../../wiki/schema.md) states file names, frontmatter,
tags, when to create a page, and the directory tree.
[AGENTS.md](../../../AGENTS.md) is the entry point. It loads the
[Fiona skill](./SKILL.md) for commands and the edit loop. When a
convention changes, change the schema. Leave the tree in that one
file.
## 3. Operations
### 3.1. Ingest
Put a new source in `ingest/`. The agent reads it, writes the
summary under `wiki/`, updates [index](../../../wiki/index.md),
updates the entity and concept pages the source touches, and
appends one dated line to [log](../../../wiki/log.md). One source
can touch many pages. Take sources one at a time when the summary
should be checked before the next file.
After the archive step, the source lives under `raw/` and is not
edited again.
An ingest has two phases. A tool fetches the source, archives it
under `raw/`, and converts it into a page marked `status: raw`.
The agent then refines that page, updates the pages it touches,
and marks it `status: refined`. The steps are section 18 of the
[Fiona skill](./SKILL.md).
### 3.2. Query
Ask against the wiki. The agent reads the index, opens the pages
that apply, and answers with citations. File a comparison, an
analysis, or a connection that should outlive the chat under
`wiki/queries/` or `wiki/comparisons/`.
### 3.3. Lint
Check the wiki for contradictions, claims a newer source has
replaced, pages with no inbound links, concepts that need their
own page, missing cross-references, and gaps a source could fill.
The health command is `fiona-assistant wiki sanity`. Style,
frontmatter, and link checks are in the [Fiona skill](./SKILL.md).
## 4. Index and log
[index](../../../wiki/index.md) is the catalog. Each page has a
link and a one-line summary, grouped by section. Update it when
a page is added. Read it first when answering a query.
[log](../../../wiki/log.md) is append-only. Each entry is one
dated bullet:
```text
- YYYY-MM-DD - what happened
```
Bump `version` and `updated` on `log.md` when appending. The log
is the timeline of ingests, queries, and lint passes.
Git holds the before and after of each entry. Every ingest cycle
and every housekeeping pass ends in one commit, so one source or
one cleanup can be reviewed or undone on its own.
## 5. Page rules
File names, frontmatter, tags, links, and when to create or split
a page are in [schema](../../../wiki/schema.md). How to fill the
frontmatter and the quality signals is section 15 of the
[Fiona skill](./SKILL.md). This file does not repeat them.
## 6. Why this works
Cross-references, summaries that still match the sources, and notes
where a new source disagrees with an older claim are the work that
usually gets dropped. The agent does that work on each ingest, so
the wiki stays current as it grows.
The human chooses sources, directs the analysis, and decides what
the pages mean. The agent does the filing.
## 7. Scope
This file states the pattern. The directory tree stays in
[schema](../../../wiki/schema.md). Commands stay in the
[Fiona skill](./SKILL.md). An Obsidian graph, Marp slides,
Dataview, or a local search engine can sit beside the wiki. This
wiki does not require them.
File diff suppressed because it is too large Load Diff
+173
View File
@@ -0,0 +1,173 @@
---
name: skill-memories
version: 1.0.1
title: SKILL_NAME Memories
created: 2026-11-18
updated: 2026-11-18
type: summary
---
# SKILL_NAME Memories
<!-- toc-start: headings 2..6 -->
- [1. How to use this file](#1-how-to-use-this-file)
- [1.1 When to read](#11-when-to-read)
- [1.2 When to write](#12-when-to-write)
- [1.3 How to write](#13-how-to-write)
- [1.4 How the memory evolves](#14-how-the-memory-evolves)
- [2. Output and wording](#2-output-and-wording)
- [2.1 Style and format](#21-style-and-format)
- [2.2 Placement and naming](#22-placement-and-naming)
- [3. Inputs and sources](#3-inputs-and-sources)
- [3.1 Where inputs come from](#31-where-inputs-come-from)
- [3.2 Quirks and parsing](#32-quirks-and-parsing)
- [4. Steps and tools](#4-steps-and-tools)
- [4.1 Commands and flags](#41-commands-and-flags)
- [4.2 Machine and shell](#42-machine-and-shell)
- [5. Recurring requests](#5-recurring-requests)
- [5.1 Patterns](#51-patterns)
<!-- toc-end -->
What users want from the SKILL_NAME skill, kept across sessions:
standing preferences, corrections, repeated request patterns, and
facts a run verified while using this skill. Preferences for the
whole wiki go to the wiki's `MEMORY.md`. Knowledge from sources goes
to pages under `wiki/`.
## 1. How to use this file
### 1.1 When to read
- **1.1.1** Read this file once [the skill](./SKILL.md) is loaded,
before its first step of the session. When it is already in
context, do not read it again.
- **1.1.2** Apply every entry that matches the request.
- **1.1.2.1** An entry overrides a default of the skill and an
entry of the wiki's `MEMORY.md`, for work done with this skill
only.
- **1.1.2.2** An entry never overrides the boundaries in the wiki's
`AGENTS.md`; when the two conflict, follow the boundary and ask
the user.
- **1.1.2.3** An entry never changes a tool contract: a command, a
flag, or a required frontmatter field.
- **1.1.3** Every heading and list item is numbered as
[sectionize-markdown](../../skills/sectionize-markdown/SKILL.md)
describes. Cite an item as `SKILL_NAME MEMORIES.md item 2.1.3`; a
new item takes the next free number in its subsection.
### 1.2 When to write
- **1.2.1** Write an entry when one of these happens while the skill
is in use:
- **1.2.1.1** The user states a requirement or preference for this
skill that outlasts the current request ("always", "never", "from
now on", "when you do X").
- **1.2.1.2** The user corrects the skill's output or a step it
took.
- **1.2.1.3** The same kind of request comes for the second time;
record the pattern and what the user wanted.
- **1.2.1.4** A run verifies a reusable fact about the skill's
inputs, hosts, or tools that the skill does not state.
- **1.2.1.5** The user explicitly asks you to remember something
for this skill.
- **1.2.2** Do not write:
- **1.2.2.1** One-off values that only apply to the current
request.
- **1.2.2.2** Passwords, tokens, cookies, personal data, or
anything the user asks to keep out.
- **1.2.2.3** Preferences that hold for any wiki work; those go to
the wiki's `MEMORY.md`.
- **1.2.2.4** Facts the skill or a wiki page already states; cite
them instead.
- **1.2.2.5** Guesses; only what the user said or a run showed.
### 1.3 How to write
- **1.3.1** Put the entry under the `###` subsection that fits.
- **1.3.1.1** When none fits, add a `###` subsection with the next
free number under the matching `##`, or a new `##` category with
the next free number.
- **1.3.1.2** Never put an entry directly under a `##`; its id
would collide with a later subsection.
- **1.3.2** Use the knowledge-entry shape of sectionize-markdown
section 4: a header line with the source tag and a short title,
one child per fact, and a last child with the ref and the date.
- **1.3.3** Source tags: `user` (the user said it), `run` (a command
or tool run showed it), `source` (a file under `raw/` states it),
joined with `+` when several agree.
- **1.3.4** The ref says where to check the fact: the user's request
and its date, the command and its output line, or a page or raw
path.
- **1.3.5** Write the entry in the same turn, then tell the user
which item was added or changed, for example "Saved to SKILL_NAME
MEMORIES.md item 2.1.1".
- **1.3.6** Bump `version` (patch for a changed entry, minor for a
new entry or subsection) and set `updated` in the frontmatter on
every change.
- **1.3.7** Append `- YYYY-MM-DD - SKILL_NAME memory: <item id> <title>`
to `wiki/log.md`, and bump that file too.
- **1.3.8** The change lands in the save of the current ingest cycle
or housekeeping pass.
- **1.3.8.1** With no cycle running, save it on its own with
`fiona-assistant git save --description "SKILL_NAME memory: <item id> <title>"`.
An entry looks like this:
```text
- **2.1.1** [user] "Reports open with the verdict"
- **2.1.1.1** The report starts with pass or fail, then the evidence.
- **2.1.1.2** Applies to every run of this skill.
- **2.1.1.3** Ref: user request YYYY-MM-DD; added YYYY-MM-DD.
```
### 1.4 How the memory evolves
- **1.4.1** Before adding an entry, look for a near-duplicate in the
same category; extend it instead and keep its id and its earliest
date.
- **1.4.2** A finding that contradicts an entry becomes its next
child, titled `OVERRIDE: ...`, with the new facts and its own ref.
- **1.4.3** An entry that no longer applies is marked
**Superseded YYYY-MM-DD** with the reason; it is not deleted.
- **1.4.4** An entry that held for several uses graduates; mark it
**Promoted YYYY-MM-DD** with the target.
- **1.4.4.1** A rule for every run of the skill moves into
[the skill](./SKILL.md).
- **1.4.4.2** A preference that turns out to hold for all wiki
work moves to the wiki's `MEMORY.md`.
- **1.4.5** Never renumber ids; pages, log lines, and chats may cite
them.
- **1.4.6** Git is the memory's history: `git log -p MEMORIES.md` in
the skill's folder shows when each entry changed and why.
## 2. Output and wording
What the skill produces and how it reads.
### 2.1 Style and format
### 2.2 Placement and naming
## 3. Inputs and sources
What the skill reads and where it comes from.
### 3.1 Where inputs come from
### 3.2 Quirks and parsing
## 4. Steps and tools
How the skill's commands and the machine behave.
### 4.1 Commands and flags
### 4.2 Machine and shell
## 5. Recurring requests
Requests that come back, and what the user wanted each time.
### 5.1 Patterns
+109
View File
@@ -0,0 +1,109 @@
---
name: memory
category: productivity
description: Give a skill its own memory, a MEMORIES.md beside its SKILL.md.
author: nvaldez
version: 1.0.1
created: 2026-10-15
updated: 2026-10-21
---
# Skill Memory
<!-- toc-start: headings 2..6 -->
- [1. What a skill memory is](#1-what-a-skill-memory-is)
- [2. Give a skill memory](#2-give-a-skill-memory)
- [3. Wire it into the skill](#3-wire-it-into-the-skill)
- [4. Use a skill memory](#4-use-a-skill-memory)
<!-- toc-end -->
A skill with memory keeps what its users want from that skill across
sessions, in a `MEMORIES.md` file beside its `SKILL.md`. The blank
file to copy is [MEMORIES](./MEMORIES.md). The wiki-wide memory is
[MEMORY](../../../MEMORY.md); this skill does not replace it.
Every heading and list item is numbered as
[sectionize-markdown](../sectionize-markdown/SKILL.md)
describes. Cite a rule as `memory skill item 2.3`.
## 1. What a skill memory is
- **1.1** One file per skill: `MEMORIES.md` in the skill's folder,
next to its `SKILL.md`.
- **1.2** It holds facts about operating that one skill:
- **1.2.1** Preferences for the skill's output.
- **1.2.2** Corrections to the skill's steps or results.
- **1.2.3** Request patterns that came back for that skill.
- **1.2.4** Facts a run verified about the skill's inputs, hosts,
and tools.
- **1.3** It does not hold:
- **1.3.1** Knowledge from sources; that is a page under `wiki/`.
- **1.3.2** Preferences for the whole wiki; those go to
[MEMORY](../../../MEMORY.md).
- **1.3.3** Passwords, tokens, cookies, or personal data.
- **1.4** Precedence, from strongest to weakest:
- **1.4.1** The boundaries in [AGENTS](../../../AGENTS.md) and tool
contracts (commands, flags, required frontmatter).
- **1.4.2** The skill's `MEMORIES.md`, for work done with that skill.
- **1.4.3** The wiki's `MEMORY.md`.
- **1.4.4** The defaults in the skill's `SKILL.md`.
## 2. Give a skill memory
- **2.1** Give a skill memory when the user asks for a skill with
memory, or when the same correction to one skill comes a second
time.
- **2.2** A new skill lives under `utils/skills_local/<skill>/`. A
skill shipped under `utils/skills/` can also get a memory; the
template never ships a `MEMORIES.md` for it, so an update leaves the
file alone.
- **2.3** Copy [MEMORIES](./MEMORIES.md) to
`<skill-folder>/MEMORIES.md`. Never edit the template copy in this
folder.
- **2.4** In the copy:
- **2.4.1** Set frontmatter `name` to `<skill>-memories`, `version`
to `1.0.0`, and `created` and `updated` to today.
- **2.4.2** Replace every `SKILL_NAME` with the skill's name.
- **2.4.3** Rename the empty categories in sections 2 to 5 to fit
the skill, or keep them. Leave section 1 as it is.
- **2.5** Add the memory section of section 3 to the skill's
`SKILL.md` and bump that file's `version`.
- **2.6** Append `- YYYY-MM-DD - memory: <skill> gets MEMORIES.md` to
`wiki/log.md`, then save with
`fiona-assistant git save --description "memory: <skill> gets MEMORIES.md"`.
## 3. Wire it into the skill
- **3.1** The skill's `SKILL.md` gets this section as its last
numbered section, with `N` set to that section's number:
```markdown
## N. Memory
- **N.1** After loading this skill, read [MEMORIES](./MEMORIES.md)
once per session. When it is already in context, do not read it
again.
- **N.2** Update it whenever an important memory about this skill
comes up: a lasting preference, a correction, a repeated request,
or a fact a run verified. Also update it whenever the user
explicitly asks you to remember something for this skill.
Section 1 of that file says how.
```
- **3.2** Keep the link relative (`./MEMORIES.md`) so the skill still
finds its memory after a move.
## 4. Use a skill memory
- **4.1** Section 1 of each skill's `MEMORIES.md` is the rule for
reading and writing it. This file does not repeat it.
- **4.2** Pick the narrowest memory that covers the fact:
- **4.2.1** It only matters while one skill runs: that skill's
`MEMORIES.md`.
- **4.2.2** It matters for any wiki work: `MEMORY.md`.
- **4.2.3** When unsure, ask the user which one.
- **4.3** When a request uses a skill that has no memory and a
memory comes up, write it to `MEMORY.md` and suggest giving the
skill one (section 2).
+160
View File
@@ -0,0 +1,160 @@
---
name: sectionize-markdown
version: 1.2.0
title: How to sectionize a markdown file
description: Number every heading and list item of a markdown file so each
rule, step, or fact has a stable id to cite.
category: documentation
created: '2026-10-14'
updated: '2026-11-19'
confidence: high
llm:
- model: Claude Opus 5.5
---
# How to sectionize a markdown file
<!-- toc-start: headings 2..6 -->
- [1. Headings](#1-headings)
- [2. List item ids](#2-list-item-ids)
- [3. Splitting long lines](#3-splitting-long-lines)
- [4. Knowledge entries](#4-knowledge-entries)
- [5. Organize by category](#5-organize-by-category)
- [6. Doing it safely](#6-doing-it-safely)
- [7. Example](#7-example)
<!-- toc-end -->
Numbers every heading and every list item of a markdown file so each
rule, step, or fact has a stable id that can be cited ("item
4.2.3"), tracked, and checked for duplicates. It suits rule files,
skill instructions, glossaries, and knowledge caches.
## 1. Headings
- **1.1** Number every heading below the title: `## N.` for sections,
`### N.M` for subsections, `#### N.M.K` below that.
- **1.2** The `#` title and the table of contents are not numbered.
- **1.3** Put a TOC of markdown links right under the title and intro.
Regenerate it whenever headings change.
- **1.4** Anchors are GitHub-style slugs: `## 5.6 Download the logs`
becomes `#56-download-the-logs`.
- **1.5** Avoid em dashes and other punctuation in headings; use a colon
(`10.7 Outcome: a match exists`). Punctuation makes the slug
unpredictable and breaks TOC links (MD051).
- **1.6** A label that only introduces a list ("Files in this
folder:") is a numbered list item, not a heading.
## 2. List item ids
- **2.1** Every list item gets a bold id right after the dash:
`- **4.2.1** Text`. Bold is two asterisks on each side; a single
asterisk is italic.
- **2.2** The id is the section number plus a running counter:
`**<section>.<n>**`. Nested items extend the parent id:
`**<section>.<n>.<m>**`, indented two spaces.
- **2.3** The counter runs through the whole section, across separate
lists split by paragraphs or code blocks. Two lists under `### 12.3`
give `**12.3.1**`…`**12.3.3**`, then `**12.3.4**`…, never a second
`**12.3.1**`.
- **2.4** Checklists keep the box first: `- [ ] **13.1** Verify …`.
- **2.5** Do not number the TOC, code blocks, or table rows.
- **2.6** State the convention in the file's first section so the next
editor follows it ("Cite an item as `item 4.2.3`").
- **2.7** Never renumber existing ids; other notes may cite them. A new
item takes the next free number in its section, even if that puts it
out of reading order. Fix the order only while the ids are still
unreleased (uncommitted).
## 3. Splitting long lines
- **3.1** A list item holding several facts becomes a short header item
plus one child per fact.
- **3.2** One child is one sentence, or two closely linked sentences.
- **3.3** Split at sentence ends (`.`, `?` or `!`, then a space and an
uppercase letter, backtick, `*`, `"` or `[`). Do not split inside
backticks or parentheses, or after `e.g.`, `i.e.`, `vs.`, `cf.`.
- **3.4** Merge fragments shorter than about 45 characters back into the
previous child; they read better together.
- **3.5** A long single sentence stays on one line. Do not cut a
sentence in half to meet a length target.
- **3.6** Leave command lines, code blocks, and table rows as they are.
## 4. Knowledge entries
A file that collects findings or lessons learned uses a fixed entry
shape so each fact is citable and the source is visible:
```text
- **<section>.<n>** [<source>] "<short title>"
- **<section>.<n>.1** <reusable fact + where it applies>
- **<section>.<n>.2** <next fact>
- **<section>.<n>.<k>** Ref: <path:line or query>; added <YYYY-MM-DD>.
```
- **4.1** The entry line holds only the source tag and the title.
- **4.2** `<source>` names where the fact was verified (a repository, a
spec, …), joined with `+` when several agree.
- **4.3** The last child is always the ref with the date it was added.
- **4.4** A finding that contradicts an entry becomes that entry's next
child, titled `OVERRIDE: …`, with its own children. Or mark the old
entry **Superseded YYYY-MM-DD** with the reason.
## 5. Organize by category
- **5.1** Group entries by topic (setup, build, deployment, …), not by
the date they were added. The date lives in the ref line.
- **5.2** Grouping puts near-duplicates next to each other. Merge them
into one entry and keep the earliest `added` date.
- **5.3** A glossary gets the same treatment: one
`###` per term under a `##` category, its definition split into
numbered items.
## 6. Doing it safely
- **6.1** Restructure with a script, not by hand, when the file has more
than a few dozen items. Hand edits drop or reorder text.
- **6.2** The script asserts that the words are preserved: same word
sequence before and after, only ids and line breaks added.
- **6.3** Verify after every pass:
- **6.3.1** No duplicate ids (`^\s*- (\[ \] )?\*\*([\d.]+)\*\*`).
- **6.3.2** Every `](#anchor)` resolves to a heading slug.
- **6.3.3** The entry count matches the original; diff titles against
`HEAD` when it does not (an uncommitted entry may explain it).
- **6.3.4** One `Ref:` line per entry.
- **6.4** Watch for editors that reformat on save (escaped `\*`, `*`
bullets padded with three spaces, lost HTML comments, fences without a language). Normalize
back and re-verify.
- **6.5** On Windows PowerShell, write helper scripts to `%TEMP%` and run
them; `python -c` with backticks breaks. Avoid printing non-ASCII to
the cp1252 console. Delete the temp scripts afterwards.
- **6.6** Keep Unix line endings and `-` bullets, and run the markdown
linter before committing.
## 7. Example
Before:
```text
## Topic
- Rule about the topic. A fact about it. How to fix it. Ref: file:line.
- Label for a group: first part of the rule, second part of the rule.
```
After:
```text
## 3. Topic
### 3.2 Subtopic
- **3.2.4** [source] "Rule about the topic"
- **3.2.4.1** A fact about it.
- **3.2.4.2** How to fix it.
- **3.2.4.3** Ref: file:line; added YYYY-MM-DD.
- **3.2.5** Label for a group:
- **3.2.5.1** First part of the rule.
- **3.2.5.2** Second part of the rule.
```
+322
View File
@@ -0,0 +1,322 @@
---
name: specification-writer
description: Load when writing or updating project specifications (SPEC.md).
Expert in creating structured and maintainable specification documents.
type: skill
version: 1.1.0
category: documentation
created: 2026-11-03
updated: 2026-11-19
---
# Specification Writer
You are an expert in writing software project specifications.
This skill provides guidance on creating structured, comprehensive, and
maintainable SPEC.md files following established best practices.
## When to Load
Load this skill when:
- Creating a new SPEC.md file for a project
- Updating or expanding an existing specification
- Reviewing specification structure and content
- Ensuring specifications follow consistent patterns
## Core Principles
### Sectionize-Markdown Conventions
Always apply sectionize-markdown conventions to every SPEC.md file.
Reference: [sectionize-markdown skill](../sectionize-markdown/SKILL.md)
- Every heading MUST be numbered: `## 1.` for sections, `### 1.1`
for subsections, etc.
- Every list item MUST have a bold ID: `- **1.1.1** Text`
- TOC MUST be present under the title with markdown links
- Anchors MUST follow GitHub-style slugs
- Never renumber existing IDs - they may be cited elsewhere
## SPEC.md Structure Template
Use this structure as the foundation for all project specifications:
```markdown
---
name: <Project Name> Specification
version: <semver>
title: Project Spec Sheet
type: specification
created: <YYYY-MM-DD>
updated: <YYYY-MM-DD>
---
# <Project Name> Specification
<!-- toc-start: headings 2..6 -->
- [1. Product Overview](#1-product-overview)
- [1.1. Purpose](#11-purpose)
- [1.2. Scope](#12-scope)
- [1.3. Non-Goals](#13-non-goals)
- [1.4. Document Conventions](#14-document-conventions)
- [2. Architecture](#2-architecture)
- [2.1. Component Diagram](#21-component-diagram)
- [2.2. Data Flow](#22-data-flow)
- [2.3. Module Structure](#23-module-structure)
- [3. Core Contracts](#3-core-contracts)
- [3.1. Interfaces](#31-interfaces)
- [3.2. Data Structures](#32-data-structures)
- [4. Package and Runtime](#4-package-and-runtime)
- [4.1. Dependencies](#41-dependencies)
- [4.2. Entry Points](#42-entry-points)
- [4.3. Installation](#43-installation)
- [5. Feature Requirements](#5-feature-requirements)
- [6. Configuration Files](#6-configuration-files)
- [7. Error Handling](#7-error-handling)
- [8. Testing](#8-testing)
- [9. Deployment](#9-deployment)
<!-- toc-end -->
This document is the build contract for <Project Name>.
A reader with this file, and no source tree, must be able to produce
the same observable software.
Status values are `Implemented`, `Partially Implemented`, `Planned`,
and `Not Implemented`.
---
```
## Detailed Section Guidelines
### 1. Product Overview
#### 1.1. Purpose
- **1.1.1** Clearly state what problem the project solves
- **1.1.2** Describe the primary value proposition
- **1.1.3** Identify the target users or audience
- **1.1.4** Define the project's mission statement
#### 1.2. Scope
- **1.2.1** **In Scope**: List what the project will do
- **1.2.2** **Out of Scope**: List what the project will NOT do
- **1.2.3** Define clear boundaries for the project
#### 1.3. Non-Goals
- **1.3.1** Explicitly state what will not be implemented
- **1.3.2** Clarify boundaries with related projects or systems
- **1.3.3** Document conscious exclusions and rationale
#### 1.4. Document Conventions
- **1.4.1** Define terminology used throughout the document
- **1.4.2** Establish status labels and their meanings
- Implemented: Feature is complete and tested
- Partially Implemented: Feature is partially complete
- Planned: Feature is scheduled for implementation
- Not Implemented: Feature is specified but not yet built
- **1.4.3** Specify numbering conventions for sections and items
- **1.4.4** Define RFC2119 keywords (MUST, SHALL, SHOULD, MAY, etc.)
### 2. Architecture
#### 2.1. Component Diagram
- **2.1.1** Provide ASCII or Mermaid diagram showing system architecture
- **2.1.2** Label all major components and their relationships
- **2.1.3** Show data flow between components with arrows or descriptions
- **2.1.4** Indicate external dependencies and integrations
#### 2.2. Data Flow
- **2.2.1** Describe how data moves through the system end-to-end
- **2.2.2** Identify key data transformations at each stage
- **2.2.3** Note where data is persisted and in what format
- **2.2.4** Document data validation and error handling points
#### 2.3. Module Structure
- **2.3.1** Document the complete directory and file structure
- **2.3.2** Describe each module's responsibility and purpose
- **2.3.3** Note dependencies between modules
- **2.3.4** Indicate which modules are public vs internal APIs
### 3. Core Contracts
#### 3.1. Interfaces
- **3.1.1** Define purpose and role of each interface
- **3.1.2** List all required methods or functions with signatures
- **3.1.3** Document expected inputs, outputs, and return types
- **3.1.4** Specify error handling expectations and exceptions
- **3.1.5** Note version compatibility requirements
#### 3.2. Data Structures
- **3.2.1** Provide complete type definitions or JSON schemas
- **3.2.2** Include concrete examples of each data structure
- **3.2.3** Document validation rules and constraints
- **3.2.4** Note backward and forward compatibility considerations
- **3.2.5** Specify serialization formats (JSON, YAML, etc.)
### 4. Package and Runtime
#### 4.1. Dependencies
- **4.1.1** List runtime dependencies with exact version requirements
- **4.1.2** List development dependencies for building and testing
- **4.1.3** Document optional dependencies and their purposes
- **4.1.4** Note any version conflicts or compatibility constraints
#### 4.2. Entry Points
- **4.2.1** Define CLI entry points and their usage
- **4.2.2** Document library entry points for programmatic use
- **4.2.3** Specify plugin or extension entry points if applicable
- **4.2.4** Include examples of invoking each entry point
#### 4.3. Installation
- **4.3.1** Document all supported installation methods
- **4.3.2** Specify platform and environment requirements
- **4.3.3** Provide verification steps to confirm successful installation
- **4.3.4** Note any post-installation configuration needed
### 5. Feature Requirements
Organize requirements by feature area. Each feature section should include:
- **5.X.1** Status: One of Implemented, Partially Implemented, Planned,
Not Implemented
- **5.X.2** Purpose: User stories and motivations for the feature
- **5.X.3** Functional requirements: What the feature must do
- **5.X.4** Non-functional requirements: Performance, security, etc.
- **5.X.5** Acceptance criteria: How to verify the feature works
### 6. Configuration Files
For each configuration file, document:
- **6.1.1** Location: Both relative path and typical absolute paths
- Note platform-specific locations (Windows vs Unix)
- **6.1.2** Purpose: What the configuration controls
- **6.1.3** Structure: Complete format and schema
- **6.1.4** Default values: What settings are used if not specified
- **6.1.5** Customization: How users can modify the configuration
### 7. Error Handling
#### 7.1. Error Classification
- **7.1.1** Transient vs permanent errors
- **7.1.2** Recoverable vs unrecoverable errors
- **7.1.3** User-facing vs internal errors
- **7.1.4** Expected vs unexpected errors
#### 7.2. Error Reporting
- **7.2.1** Logging strategy and verbosity levels
- **7.2.2** User notification mechanisms (CLI, UI, etc.)
- **7.2.3** Error codes and their meanings
- **7.2.4** Error message format and content
#### 7.3. Recovery Strategies
- **7.3.1** Automatic recovery mechanisms and retries
- **7.3.2** Manual recovery procedures and user actions
- **7.3.3** Data consistency guarantees during failures
- **7.3.4** Rollback and undo capabilities
### 8. Testing
#### 8.1. Test Strategy
- **8.1.1** Testing pyramid: Unit, integration, system, E2E
- **8.1.2** Test coverage targets for different test types
- **8.1.3** Test environments and their configurations
- **8.1.4** CI/CD integration for automated testing
#### 8.2. Test Cases
- **8.2.1** Critical path tests covering core functionality
- **8.2.2** Edge case tests for boundary conditions
- **8.2.3** Regression tests for known issues
- **8.2.4** Performance and load tests if applicable
### 9. Deployment
#### 9.1. Release Process
- **9.1.1** Versioning scheme (SemVer, CalVer, etc.)
- **9.1.2** Release checklist and required steps
- **9.1.3** Rollback procedures for failed deployments
- **9.1.4** Release notes and changelog requirements
#### 9.2. Distribution
- **9.2.1** Package repositories and distribution channels
- **9.2.2** Installation methods for end users
- **9.2.3** Update mechanisms and version management
- **9.2.4** Offline or air-gapped installation options
## Sectionize-Markdown Integration
**CRITICAL**: Every SPEC.md file you create or modify MUST follow
sectionize-markdown conventions completely.
Before finalizing any SPEC.md:
1. Apply numbered headings (## 1., ### 1.1, #### 1.1.1)
2. Add bold IDs to all list items (- **1.1.1**)
3. Generate or update the TOC with markdown links
4. Ensure all anchors resolve correctly
5. Verify no duplicate IDs exist
Use the sectionize-markdown skill as the definitive reference for
all sectionizing conventions and requirements.
## Quality Checklist
Before marking a SPEC as complete, verify:
- [ ] **Structure**: All required sections are present
- [ ] **Numbering**: All headings and list items are numbered correctly
- [ ] **TOC**: Table of contents is present and accurate
- [ ] **Status**: Every feature section has a status line
- [ ] **Examples**: Code and configuration examples are provided
- [ ] **Cross-references**: All internal links resolve correctly
- [ ] **Consistency**: Terminology and formatting are consistent
- [ ] **Completeness**: All acceptance criteria are defined
- [ ] **Sectionized**: Follows sectionize-markdown conventions completely
## Maintenance Guidelines
- **Versioning**: Increment version in frontmatter with each update
- **Changelog**: Maintain updated and created dates in frontmatter
- **Review**: SPEC should be reviewed before major implementation
- **Sync**: Keep SPEC in sync with implementation (update status)
## Tools and Automation
When working with SPEC files:
- Use scripts to verify section numbering consistency
- Automate TOC generation to avoid manual errors
- Validate all internal links before committing
- Check for duplicate IDs across the entire document
- Run markdown linters to ensure formatting quality
## Common Pitfalls
- **Unnumbered items**: Every list item MUST have a bold ID
- **Broken anchors**: Always verify all TOC links resolve
- **Inconsistent status**: Use consistent status labels throughout
- **Missing examples**: Always include examples for data formats
- **Ambiguous requirements**: Requirements must be testable and verifiable
- **Overly verbose**: Be concise but comprehensive
- **Under-specified**: Include enough detail for implementation