Files
nvaldez b0f07593b5 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>
2026-11-19 10:20:04 +01:00

6.2 KiB

name, version, title, description, category, created, updated, confidence, llm
name version title description category created updated confidence llm
sectionize-markdown 1.2.0 How to sectionize a markdown file Number every heading and list item of a markdown file so each rule, step, or fact has a stable id to cite. documentation 2026-10-14 2026-11-19 high
model
Claude Opus 5.5

How to sectionize a markdown file

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:

- **<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:

## 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:

## 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.