Planning Second Brain

Create and maintain a project second brain without replacing source-of-truth planning files.

Core Contract

• Treat task_plan.md, findings.md, and progress.md as the only source of truth (SOT).
• Write second-brain outputs into docs/notes using Obsidian-compatible Markdown.
• Never let docs/notes overwrite or redefine source-of-truth files.
• Route all entrypoints through one deterministic capture workflow.

Required Skill Composition

1. Invoke planning-with-files first for primary planning workflow.
2. Invoke obsidian-markdown when writing or updating second-brain Markdown.

Trigger Contract

Use this skill when users ask to:

• keep project memory over time
• summarize milestones into reusable notes
• record stable decisions and knowledge
• build an Obsidian-friendly project knowledge base
• read intents: find prior decision, look up past context, trace project timeline, retrieve existing second-brain note

Do not use this skill for unrelated implementation work that does not involve capture, summarization, or project memory publishing.

Output Locations

• docs/notes/index.md
• docs/notes/projects.md
• docs/notes/decisions.md
• docs/notes/knowledge.md
• docs/notes/harvest-quality.md
• docs/notes/projects/<project>/timeline/YYYY-MM-DD.md
• docs/notes/decisions/*.md
• docs/notes/knowledge/*.md
• docs/notes/harvest-quality/YYYY-MM-DD-<project-slug>-harvest-review.md
• docs/notes/harvest-quality/rollups/YYYY-MM-<project-slug>-harvest-optimization.md

Create missing folders/files when absent.

Progressive Disclosure Read Workflow (Required)

Follow this read order before any retrieval or context lookup:

1. Read docs/notes/index.md to discover available hubs.
2. Read the intent hub: docs/notes/projects.md, docs/notes/decisions.md, or docs/notes/knowledge.md.
3. Read only targeted leaf notes that match the intent.

Stop condition:

• Stop when the target note is found, or after two consecutive reads that add no novel information.

Hard constraints:

• Never start from deep leaves unless the user provides an exact path.
• Treat docs/notes as retrieval-only; never capture or summarize docs/notes back into docs/notes.
• Preserve the anti-recursion guard and existing SOT-only contract (task_plan.md, findings.md, progress.md).
• Do not expand read scope beyond the minimal files needed for the requested intent.

Reference example:

• references/progressive-disclosure-read-example.md

Deterministic Workflow (Required)

Run this workflow in order for every entrypoint (manual trigger phrases, slash-command wrappers, and plugin-driven invocation):

1. Preflight
   • Confirm SOT inputs exist: task_plan.md, findings.md, progress.md.
   • Confirm output root: docs/notes.
   • Set mode: capture, status, audit, review, or optimize.
   • For optimize mode, collect optional user-provided report directories as additional input roots.
2. Bootstrap
   • Ensure required minimal docs/notes files and templates exist.
   • Apply contract in references/publishing-and-dedupe.md.
3. Extract Candidates
   • Apply contracts in references/extraction-and-classification.md.
4. Classify
   • Route each candidate using the classification decision table contract.
5. Publish
   • Append same-day timeline events and update decision/knowledge notes with dedupe.
6. Verify and Report
   • Run verification checklist.
   • For review and optimize, apply references/quality-reports.md.

Candidate Schema and Extraction Rules (Required)

Candidate fields MUST include:

• source_ref, change, why, candidate_type, confidence
• optional: sot_fingerprint, exclusion_reason, unresolved_source_ref

Apply full extraction/classification contract in references/extraction-and-classification.md.

Publish Confirmation Semantics (Required)

1. Extract candidate.
2. Validate schema fields and thresholds.
3. Publish into target note.
4. Mark committed after publish succeeds.

Apply full publishing contract in references/publishing-and-dedupe.md.

First-Run Bootstrap (Required)

If docs/notes is missing, or if any required minimal file is missing, bootstrap from references/bootstrap/.

Apply the required minimal files list and bootstrap rules in references/publishing-and-dedupe.md.

Publishing Strategy

Apply classification, timeline, and milestone publish contracts in references/extraction-and-classification.md.

Review Report Mode (Required)

Use review mode to evaluate harvest output quality and persist one reusable report for later optimization planning.

Apply full review contract in references/quality-reports.md.

Review Rollup Mode (Required)

Use optimize mode to aggregate multiple review reports into one optimization roadmap.

Apply full rollup contract in references/quality-reports.md.

Execution Contract (Required)

• Treat trigger methods as entrypoints only (manual phrases, slash-command wrappers, plugin-driven calls).
• MUST route all entrypoints through the same deterministic workflow.
• Produce equivalent output for equivalent source input regardless of trigger method.
• Do not implement separate dedupe behavior per trigger entrypoint.
• Keep plugin-driven capture behavior contract-compatible with manual entrypoints.
• Keep review and optimize modes repo-agnostic. Do not hardcode project-specific heuristics as universal rules.

Source Extraction Boundaries (Required)

Extract with allowlist rules from source-of-truth files. Do not summarize everything.

Apply full allowlist/denylist and thresholds in references/extraction-and-classification.md.

Harvest Exclusion Markers

Support explicit exclusion markers inside source-of-truth files:

• <!-- harvest:exclude:start -->
• <!-- harvest:exclude:end -->

Ignore content inside this block during harvest publishing.

Anti-Recursion Guard

• Do not summarize notes under docs/notes back into new notes.
• Use source-of-truth files as input only (task_plan.md, findings.md, progress.md).
• Skip entries that only describe harvest's own publishing activity.

Dedupe and Fingerprint Contract (Required)

• Timeline events MUST include sot_fingerprint.
• Compute sot_fingerprint from normalized source_ref + change + why.
• Same timeline day + same sot_fingerprint means no-op (do not append duplicate block).
• Equivalent source input must produce equivalent no-op behavior across manual and plugin entrypoints.

Fingerprint normalization:

1. Trim leading/trailing whitespace on source_ref, change, and why.
2. Collapse internal whitespace to single spaces.
3. Lowercase each part.
4. Join as <source_ref>||<change>||<why>.
5. Compute SHA-256 hex lowercase.

Reference example:

• references/publishing-and-dedupe.md

Note Rules

• Keep notes concise and reusable.
• Include traceability metadata in formal notes.
• Summarize; do not paste large verbatim source-of-truth sections.

Verification Checklist

Before finalizing updates:

1. Every formal note has source_files, source_date, and source_ref.
2. Every timeline event has source_ref and sot_fingerprint.
3. docs/notes/index.md links to latest decisions and knowledge.
4. No reverse edits were made to task_plan.md, findings.md, progress.md by second-brain steps.
5. No large copied source-of-truth blocks appear in formal notes.
6. In review mode, report file includes scorecard, deductions, and path-based evidence.
7. In optimize mode, rollup file includes coverage counts, aggregated scores, roadmap priority, and source report paths.
8. In optimize mode, rollup file includes input root resolution results (included + skipped + reasons).

Failure Handling

• If source_ref cannot be resolved, set note status: draft and record unresolved_source_ref.
• Do not block the source-of-truth workflow because of second-brain publish errors.

Non-Goals

• Do not modify global IDE/user rule files.
• Do not add mandatory always-on conversation loops.
• Do not turn this skill into a general cross-skill memory engine.
• Do not collect or persist tool chatter as project knowledge.

Anti-Patterns

• Treating second-brain notes as execution-state files.
• Creating parallel truth that conflicts with source-of-truth planning files.
• Defining trigger-specific behavior that diverges from the deterministic workflow.