Bruno-Cunha-Souza/ValarMindSkills / skills/obsidian-brain
obsidian-brain
VerifiedProject memory in Obsidian vault — brain/<slug>-brain.md index + atomic sessions/topics/decisions. Auto-activates when CLAUDE.md/AGENTS.md refs vault.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 23.9 KB |
| references/READING_AND_SEARCHING.md | markdown | 10.4 KB |
| references/SESSION_LIFECYCLE.md | markdown | 8.9 KB |
| references/STRUCTURE.md | markdown | 12.0 KB |
| references/WRITING_RULES.md | markdown | 12.7 KB |
references/WRITING_RULES.md
View on GitHub> Reference companion for the [obsidian-brain](../SKILL.md) skill.
# Writing Rules
How to write to the brain without bloating it.
## Atomic notes
One idea per note. If a note covers two distinct topics, split it.
| Test | If the answer is yes, split |
| :--- | :--- |
| Could one half be useful in a session that does not need the other half? | Yes → split |
| Are the two halves linked by "and also"? | Yes → split |
| Would a single one-sentence summary cover both? | No → split |
Split by creating a new topic note and updating wikilinks in the index and any session that references the original.
## Decide what to write
Before writing anything, check the trigger matrix:
| Signal | Target |
| :--- | :--- |
| User asked something the brain did not previously cover and the answer survives the session | `sessions/YYYY-MM-DD-<slug>.md` (append) |
| Non-obvious project fact discovered (architecture, constraint, gotcha) | `topics/<topic>.md` (atomic, dedupe first) |
| Trade-off explicitly chosen ("we picked X because Y") | `decisions/NNNN-<slug>.md` (immutable ADR) |
| Pending task that survives the session | `> [!todo]` block in active session note |
| Open question to revisit | `> [!question]` block in active session note |
If no trigger fires, **do not write**. Bias toward fewer notes.
## Dedupe before creating
The brain's worst failure mode is duplicate topic notes (e.g., `auth-middleware.md` and `auth-mw.md` saying the same thing). Always dedupe first.
### Topic dedupe
```bash
# Search by candidate name
obsidian search query="<candidate topic name>" limit=10
# List all topics
obsidian search tag="brain-topic" total
```
If a near-duplicate exists:
- **Refine** — add the new finding as a bullet, update `updated:` property.
- **Merge** — if two existing topics overlap, propose a merge to the user before acting.
### Decision dedupe
```bash
# Search ADRs by keyword
obsidian search query="<key term>" tag="brain/adr"
```
If the decision was already made:
- **Reference** the existing ADR from the new session note. Do not re-decide.
- **Supersede** if the original decision changed — create a new ADR with `supersedes: "[[NNNN-<old>]]"` and patch the old ADR's `status: superseded` and `superseded_by: "[[<new>]]"`.
## ADR triggers
Create an ADR (`decisions/NNNN-<slug>.md`) when **all** of these hold:
1. A clear trade-off was named (Option A vs Option B).
2. A choice was made between them.
3. The choice is non-obvious enough that a future reader would ask "why?"
Examples that qualify:
- "We picked Bases over Dataview because Dataview is slow on large vaults."
- "We chose flat `topics/` over nested `topics/<area>/<topic>.md` because Obsidian Bases ignores folder hierarchy."
- "We dropped server-side rendering for this route because it broke streaming."
Examples that do **not** qualify (not ADRs):
- "We renamed `foo` to `bar`." → session note bullet only.
- "We installed package X." → topic note if non-obvious; otherwise nothing.
- "We tried Y and it didn't work." → session note `> [!warning]` callout, not an ADR.
ADRs are **immutable** once written. To change a decision, supersede with a new ADR, never edit the original.
## Append-only sessions
Session notes are append-only within a single day. The file is `brain/sessions/YYYY-MM-DD-<slug>.md`.
### First write of the day
Create the file from the [session template](STRUCTURE.md#session-note-template). Prefer the `Write` tool with the absolute path — `obsidian create` is exemplified with `name=` only in the local `obsidian-cli` skill, so `path=` for create is **verify** territory:
```bash
# Preferred — use the harness Write tool on:
# <brainRoot>/sessions/YYYY-MM-DD-<slug>.md
# CLI alternative (verify with `obsidian help create` first):
obsidian create path="brain/sessions/YYYY-MM-DD-<slug>.md" content="<seeded body>" silent
```
### Subsequent writes that day
If the session note `brain/sessions/YYYY-MM-DD-<slug>.md` already exists today, **append, never recreate**:
```bash
obsidian append file="YYYY-MM-DD-<slug>" content="\n\n## Found (continued)\n- <new bullet>"
```
`obsidian append` is exemplified in the local `obsidian-cli` skill — safe to use. The fallback is `Edit` on the file with `old_string` matching the last existing line and `new_string` being the same line plus the appended block.
If you discover prior bullets are wrong, **add a correction below**, do not edit prior content. The corrupted bullet is part of the session record — preserving it preserves the audit log.
### Multiple sessions per day
If a single day has two distinct sessions, append a `<short-slug-2>` to the second filename: `2026-04-24-auth-refactor.md` and `2026-04-24-bases-rewrite.md`.
## Atomic-rewrite topics
Topic notes are different — they evolve. When you refine a topic:
1. Read the existing note.
2. Replace it entirely with the refined version, preserving all old bullets that are still true.
3. Increment `updated: YYYY-MM-DD`.
Prefer the `Write` tool (overwrites by design):
```bash
# Use the Write tool on <brainRoot>/topics/<topic>.md with the refined body.
```
The CLI alternative `obsidian create path="..." content="..." overwrite silent` is **verify** — the `overwrite` flag is not exemplified in the local `obsidian-cli` skill. If you choose the CLI route, run `obsidian help create` first to confirm the flag exists; on failure, drop to `Write`.
Then update the timestamp surgically (this command is exemplified in the CLI skill — safe to use):
```bash
obsidian property:set name="updated" value="YYYY-MM-DD" file="<topic>"
```
## Surgical property updates
For any case where only a frontmatter field changes, use:
```bash
obsidian property:set name="<field>" value="<value>" file="<note-name>"
```
Common cases:
| Case | Command |
| :--- | :--- |
| Touch updated date | `obsidian property:set name="updated" value="YYYY-MM-DD" file="<note>"` |
| Add a topic to a session | `obsidian property:set name="topics" value='["[[topic-x]]","[[topic-y]]"]' file="<session>"` |
| Mark ADR superseded | `obsidian property:set name="status" value="superseded" file="<ADR>"` then set `superseded_by`. |
Surgical updates preserve the rest of the note (clean Git diff, no body churn).
## Fallback for property updates
When the CLI is unavailable, use `Edit` on the frontmatter:
```python
# Pseudocode — actual impl uses Edit tool with the YAML lines as old_string/new_string.
old = "updated: 2026-04-23"
new = "updated: 2026-04-24"
```
Match the exact line including indentation. Do not rewrite the entire frontmatter block.
## Wikilink hygiene
Two failure modes produce orphan notes in the graph view. Avoid both.
### Filename-only, never path-prefixed
Obsidian resolves wikilinks **from the vault root**, not from the file's directory. Use the filename only:
```markdown
✅ [[2026-04-25-ci-cd-generator|2026-04-25]] ← session note (brain-internal)
✅ [[0001-pick-bases-over-dataview|0001]] ← decision note (brain-internal)
✅ [[auth-middleware]] ← topic note (brain-internal)
✅ [[valarmindskills-brain|Brain]] ← index (pointed to by sibling brain notes; intra-brain only)
❌ [[sessions/2026-04-25-ci-cd-generator|2026-04-25]] ← path doesn't resolve
❌ [[brain/topics/auth.md|Auth]] ← path + extension both wrong
❌ [[../brain/<slug>-brain]] ← relative paths never resolve
❌ [[prompt-engineering]] ← project doc, not a brain note (see § Brain isolation below)
```
Filenames must be globally unique within the vault. The brain's naming conventions are already designed for this (timestamped sessions, ID-prefixed ADRs, slug-prefixed index).
### Always link back to the index
Every session, topic, and decision note must have a `## Related` section in its body that includes:
- `[[<slug>-brain|Brain]]` — the project's brain index (mandatory).
- Every wikilink also declared in frontmatter (`topics:`, `decisions:`, `related:`) — repeated as a body wikilink.
**Why repeat frontmatter wikilinks in the body?** Obsidian's graph view does **not** by default follow wikilinks declared only in frontmatter properties. A session whose only `[[<some-topic>]]` reference is in `topics: ["[[<some-topic>]]"]` will appear as an orphan even though the link technically exists. The body wikilink fixes this — it is graph-visible and backlinks-visible everywhere.
The `## Related` section is the last block of every note. See [STRUCTURE.md § Session note template](STRUCTURE.md#session-note-template) for the canonical shape.
### Brain isolation — closed graph in both directions
Brain (including the index, sessions, topics, and decisions) is a **closed graph**. No node in `brain/` wikilinks to project docs, and no project doc wikilinks to a node in `brain/`. The graph of *what happened* (brain) and the graph of *how things work* (project docs) stay visually and structurally separate.
| Allowed wikilink target | Example | Notes |
| :--- | :--- | :--- |
| Brain index | `[[<slug>-brain\|Brain]]` | Pointed to by sibling brain notes only. |
| Sibling brain note (same project) | `[[<topic>]]`, `[[NNNN-<slug>]]`, `[[YYYY-MM-DD-<slug>]]` | Intra-brain only. |
| Forbidden wikilink target | Why |
| :--- | :--- |
| Project skill notes (`[[prompt-engineering]]`, `[[celebrimbor]]`) | Belongs to the docs graph; mention in prose with backticks instead. |
| MOCs (`[[Skills]]`, `[[ValarMindSkills]]`) | Same — there is no boundary node; brain is fully isolated. |
| Architecture / general docs (`[[Arquitetura]]`, `[[CLAUDE.md]]`) | Same. |
The reverse is **also forbidden**: never edit a project doc to add `[[brain/<slug>-brain]]` or `[[<topic>]]`. The `Navegação` section of project MOCs must not list the brain.
To mention a skill or doc in the body of a brain note, use backticks:
```markdown
✅ A skill `prompt-engineering` audita o `SKILL.md` recém-escrito.
❌ A skill [[prompt-engineering]] audita o `SKILL.md` recém-escrito.
```
Phase 5 of the SKILL (suggest updating main docs) is the **only** mechanism by which the brain may influence project docs — and it is **prose, never a wikilink**. There is no boundary node; the whole brain is closed.
### Self-check before saving
Before writing any brain note, scan its wikilinks:
- All `[[...]]` resolve to a real `.md` file by filename only?
- Sessions/topics/decisions have a `## Related` section linking back to `[[<slug>-brain|Brain]]`? (The index itself does not need a `## Related` — it is pointed to, never points to siblings.)
- Every frontmatter wikilink is also present as a body wikilink?
- All wikilinks point to brain notes (sessions, topics, decisions, **or the index**) — none point to project docs (`Skills/<slug>`, MOCs, `Arquitetura`, etc.)? The index follows the same rule as the rest of the brain — there is no boundary-node exception. Use backticks for textual mention of project docs instead.
If any answer is no, fix before saving. Orphans accumulate silently — graph view is the only signal, and you may not notice until the graph is already a mess.
## Token economy in writing
| Rule | Why |
| :--- | :--- |
| Bullets > prose | Easier to skim, easier to extend, fewer tokens. |
| Wikilinks > full quotes | The graph does the work; quotes duplicate. |
| `> [!summary]` first | Readers (human or agent) decide in 1 second whether to read further. |
| ≤6 bullets per summary | More than 6 = the section is two topics; split. |
| One-sentence definitions | If the topic needs two sentences to define, the topic is too big. |
| Cite session by wikilink, not by paste | Sessions are the audit log; copying their content into topics duplicates. |
## Refuse `Notes/`
Before any write, check that the target path does not fall under any directory marked read-only by the project's `CLAUDE.md`. In this repo:
- `../ValarMindObsidian/Notes/` is read-only — refuse all writes.
- The harness has a hook (`block-notes-write.sh`) and `permissions.deny` as defense-in-depth.
Skill enforces the rule first; the harness backs it up. If you ever encounter a write failure with `Notes/` in the path, do not retry — surface the error to the user.
## Refuse main-doc writes
The brain does not write to the project's main docs (`<project-MOC>.md`, `Arquitetura.md`, `Skills/<slug>/<slug>.md`). Per [SKILL.md Phase 5](../SKILL.md#phase-5--suggest-updating-main-docs):
1. Suggest the update with one line.
2. Wait for user approval.
3. Hand off to `@obsidian-markdown` for syntax and `@obsidian-cli` for the write.
The brain is not a doc-update mechanism. It tracks history and proposes; the human approves.
The reverse is also forbidden: **never** edit a project doc to add a wikilink to a brain node. Brain stays out of the project documentation graph entirely — Phase 5 produces prose suggestions, never a `[[brain/...]]` link in a project MOC.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |