5.4 KiB
Dev Brain schema
The registered projects are authoritative. This vault is a derived, human-readable wiki.
Managed paths
DS4Server manages purpose.md, schema.md, index.md, skills.md, log.md, and topic pages below projects/, subsystems/, concepts/, decisions/, invariants/, workflows/, and skills/. Topic pages must opt in with dev_brain: true. Other notes, hidden files, Obsidian settings, attachments, and trash are never modified.
Topic frontmatter
---
dev_brain: true
type: subsystem # project, subsystem, concept, decision, invariant, workflow, or skill
project: Registered project name
status: verified # verified, stale, or needs-review
verified_at: 2026-07-27T12:00:00Z
sources:
- project: Registered project name
path: src/example.rs
symbol: optional_symbol
revision: latest-commit-containing-this-file-content
# For a clean tracked file, use `git log -1 --format=%H -- src/example.rs`,
# or a unique lowercase hex prefix of at least 7 characters. Use hash when
# this file differs from HEAD, is untracked, or the registered project is not Git.
---
project names a registered project, not this Dev Brain vault; dev_brain_info lists the exact registered names and folders. Each source path is relative to that registered project's folder; never resolve it inside the vault. Cite only files that support the page's claims, not every dirty file in the project. Each source has exactly one evidence version: revision or a lowercase SHA-256 hash. A revision is the newest commit that changed that source file, returned by git log -1 --format=%H -- path; validation requires that per-file revision and compares its file content with the current clean file. Every source therefore has its own revision; never stamp all sources with the repository's overall HEAD. Use a hash when that specific file differs from HEAD, is untracked, or its registered project is not Git.
Skills
Skills are on-demand instructions stored as one Markdown file per skill below skills/. They use the same provenance and status fields as topic pages, set type: skill, and additionally require name and description frontmatter. Names contain 1–64 lowercase letters, digits, or hyphens, with no leading, trailing, or consecutive hyphens. Descriptions contain 1–1024 characters and explain both what the skill does and when to use it. Only skills whose status and current evidence are both verified appear in generated skills.md and the session system prompt. The prompt exposes each verified skill's name, description, and Markdown path; read the complete matching file on demand before following it. index.md lists all managed topic pages, while skills.md lists verified skills only. Do not hand-edit either generated index.
Files with built_in: true are app-managed skills restored from the DS4Server bundle. Do not create or edit them by hand.
---
dev_brain: true
type: skill
name: review-release
description: Verify a release candidate against the project checklist. Use before publishing a release.
project: Registered project name
status: verified
verified_at: 2026-07-27T12:00:00Z
sources:
- project: Registered project name
path: docs/releasing.md
revision: full-or-unique-short-clean-git-revision
---
Compilation
Read the purpose first. Examine high-signal manifests, documentation, schemas, entry points, public interfaces, and tests. Create the smallest coherent topic set that answers the purpose; do not mirror every source file. Use ordinary Obsidian wikilinks and embeds to connect topics.
Querying
Start with index.md or ranked search, then follow links and backlinks. A verified page is authoritative only while all recorded evidence is current. Treat stale pages as navigation leads and needs-review pages as explicit uncertainty; check project sources before making claims from either.
Refresh and semantic validation
When validation reports drifted sources, handle each listed file independently: re-read it, compare its current behavior with the page's documented findings, update, split, merge, or retire affected knowledge, then update only that source's revision or hash. For a large revision-backed file, git diff <recorded-revision> -- path shows the change from the recorded evidence to the current working-tree version; use it to focus the review, then read enough current context to validate the affected findings. Inspect the commits affecting that path since the recorded revision as well. When code was removed, inspect the full commits and search the current project, callers, and tests before concluding the behavior disappeared: it may have been renamed, replaced, or moved into another file that should replace or join the page's cited sources. Repeat for every listed file and re-run validation. Keep index.md exact, and append a material update entry to log.md with source revisions. Only mark a page verified after its claims have been checked against its current evidence. Unsupported conclusions stay needs-review.
Publication
Call dev_brain_info, then maintain these pages with the ordinary file tools. Append material updates to log.md; index.md and skills.md are generated and should not be hand-maintained. Finish with dev_brain_validate. Structural or provenance errors must be repaired, while broken links are warnings so valid work remains editable instead of being discarded.