r007b34r/opencode-obsidian-knowledge-workflow/note-promotion

note-promotion

Constraints

• NEVER promote everything; require stability + reuse + independence
• NEVER polish before deciding; score first, format only if promoting
• NEVER create notes without integration targets (minimum 2 links)
• NEVER write without user confirmation
• NEVER overwrite source voice; preserve strong original phrasing

Trigger Boundary

Use when: upgrade material into formal note, decide if finding is worth preserving, turn synthesis output into stable note, create linkable knowledge unit, user says "promote" or "stabilize."

Do NOT use for:

• First-pass inbox routing -> inbox-triage
• Note relationship discovery -> connection-review
• Week-level meaning extraction -> weekly-synthesis
• Vault system health diagnosis -> vault-health-feedback

Boundaries

• Owns: promotion decision, note type selection, integration planning, write execution
• Delegates to: connection-review (new note needs integration links), inbox-triage (material too raw)
• Never absorbs: inbox routing, relationship analysis, synthesis, health diagnosis

Continuations

Companion Skill

All vault operations follow obsidian-mcp. Forbidden: obsidian_patch_note, obsidian_append_to_note. Verify every write through readback.

Procedure

Phase 1: Score

When scoring, read references/examples.md for promotion calibration.

Apply promotion test (>=3/5 to promote):

Score < 3: recommend wait / keep raw / archive. Score >= 3: proceed to Phase 2.

Phase 2: Type Selection

Phase 3: Plan

Define: title, tags, links (integration targets), write strategy (create new or merge into existing).

Phase 4: Execute (after user confirmation only)

When writing promoted notes, read references/templates.md for note structure.

1. obsidian_write_note overwrite:false for new notes
2. obsidian_replace_in_note for merging into existing
3. Read back and verify frontmatter, content, links

<details> <summary>Edge Cases (expand when decision is unclear)</summary>

• Material scores 3/5 but all points are weak: default to "wait" -- borderline cases benefit from time
• Material is excellent but has zero link targets: cannot promote yet; suggest creating a topic-note first
• Source is a synthesis output: check if synthesis-note type is appropriate or if the thesis deserves idea-note treatment
• Multiple candidates from same source: promote the strongest one; note others as "watch" items
• Material overlaps with existing note: merge strategy preferred over creating near-duplicates

</details>

Gotchas

Gotcha 1: Promoting every good idea

What happens: Agent marks most material as worth promoting Why it is wrong: Creates hollow vault growth; promoted notes without stability become noise Correct approach: Apply scoring strictly; default to "wait" when uncertain

Gotcha 2: Promotion as polishing

What happens: Agent rewrites and beautifies content without deciding if promotion is warranted Why it is wrong: Polishing is not promotion; a well-written fragment is still a fragment Correct approach: Score first, decide promote/wait, THEN format if promoting

Gotcha 3: Island notes without links

What happens: Agent creates a promoted note with no links to existing knowledge Why it is wrong: Unlinked notes are undiscoverable; defeats the purpose of promotion Correct approach: Require at least 2 integration targets before writing

Validators (CI only, not runtime)

• validators/pre-check.sh: Confirms source material exists and is readable
• validators/post-check.sh: Verifies promoted note has frontmatter, >=2 links, and correct type tag

Exit Criteria

• Promotion decision is explicit with score and per-criterion evidence
• Weak material has not been polished into fake clarity
• Integration targets are named (>=2 links)
• If written: note exists, frontmatter correct, content reads back correctly