Skip to content
Baseworks KB

Document Revision Standard

Created 2026-04-18
Tags vault-and-toolingstandardsrevisionsdocumentation

How we track revisions on long-form vault documents that go through multiple edit passes.

Why

Section titled “Why”

Git history is the authoritative record of what changed and when. But when looking back at a document months later, reading commit messages is not how anyone actually reconstructs “why did we change this?” The Editorial Notes section inside the document itself is where that reasoning lives.

The goal is a human-readable revision log alongside the document, not a replacement for git.

What documents this applies to

Section titled “What documents this applies to”
  • Session summaries (02-areas/educational-programs/study-groups/*/session-summaries/)
  • Blog posts and website articles (02-areas/website/blog-articles/, 02-areas/website/pages/)
  • Platform lesson summaries (summaries of Primer lessons and any other platform-hosted educational content, once these are structured in the vault)

For short operational documents (inbox items, meeting notes, transient plans), git history alone is sufficient; no Editorial Notes section is needed.

The pattern

Section titled “The pattern”

Every document of the types listed above ends with an ## Editorial Notes section. The section is always present — even on a first draft that has not been revised yet, the section exists with a single line recording the initial generation.

Structure

Section titled “Structure”
## Editorial Notes


*Initial draft generated from [source] via [process], YYYY-MM-DD.*


### Round 1 revision (YYYY-MM-DD)


*Reviewer: [Name]. Reviewed by: [Claude Code on Machine / direct edit].*


Summary of what changed and why.


**Structural**
- Removed/moved/renamed X because Y


**Content**
- Trimmed X section because Y
- Rewrote X for Y reason


**Corrections**
- Fixed factual error X → Y
- Attribution corrected: A → B


**Notes for future work** (optional)
- Observations about the document itself or the process


### Round 2 revision (YYYY-MM-DD)


*Reviewer: [Name]. Reviewed by: [Claude Code on Machine / direct edit].*


(Same structure as Round 1.)

Rules

Section titled “Rules”
  1. Every revision pass gets its own Round heading. Don’t merge multiple passes into one section; each pass is a distinct record.
  2. Date and reviewer are mandatory at the top of each Round section.
  3. Explain the why, not just the what. Git shows what changed; Editorial Notes capture the reasoning. “Removed ‘What We Did Not Cover’ section” is insufficient on its own — the reasoning (“not useful for student revision material; better suited to internal/instructor notes”) is the part that carries forward.
  4. Skill-improvement notes belong here. If a revision surfaces a recurring failure mode of the generating skill (e.g., “FSA is the least inferable concept from movement descriptions alone”), note it at the bottom of the Round section so the skill can be updated.
  5. Don’t delete prior Round sections when adding a new one. The log is cumulative.

Example — see the reference implementation

Section titled “Example — see the reference implementation”

Spring 2026 Session 2 Summary is the reference implementation. Its Editorial Notes section shows both a Round 1 (structural + content review by Asia) and a Round 2 (voice + form-section density review by Patrick + Claude), with each round producing distinct changes to the document and distinct notes for skill improvement.

Integration with skills

Section titled “Integration with skills”

The following skills in .claude/skills/ reference this standard in their workflow:

  • /session-summary — Phase 7 (index update & commit) references this standard; every generated summary includes an ## Editorial Notes section with the initial-draft line
  • /write-blog-post — the final save step references this standard; blog drafts include the Editorial Notes section before publication
  • Future /write-lesson-summary skill (not yet built) — will reference this standard when created

When a revision is made to an existing document, the editor (Asia, Patrick, or Claude acting on their behalf) adds a new Round section following the pattern above. For edits made directly by Asia or Patrick in Obsidian, adding the Round section manually after the edits is the expected workflow.

When NOT to add a Round section

Section titled “When NOT to add a Round section”
  • Typo fixes (single-character or single-word corrections with no content impact)
  • Frontmatter-only changes (adding a tag, correcting a date)
  • Wikilink updates driven by file moves or renames
  • Vault-sync auto-commits

In all other cases — including rewording, restructuring, adding new content, fact-checking corrections, and voice-alignment passes — add a Round section.

Section titled “Related”