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:
@@ -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:
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -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
@@ -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
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
```
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user