reason

name	reason
description	Proactively reason on vault captures — draft proposals, queue deeper research, surface insights. Triggers on: '/reason', 'think on my captures', 'what needs action', 'morning review', 'process my ideas'.

Reason Skill

Turn passive captures into active work. Scan recent vault items, draft proposals where the vault has enough context, queue deeper research where it doesn't.

Read the yaml config block in CLAUDE.md for streams and thresholds first.

Pipeline

Scan vault (last 48h) → Identify actionable items → Draft or queue research → File insights back → Summary

---

Stream-Scoped Mode

If invoked with a stream name (/reason side-project):

1. Read vault/streams/{stream}.md for goals and context
2. Consider only items with a matching stream_id
3. Draft proposals scoped to that stream's Active Goals
4. Skip the general scan

Step 1: Scan

Read recent files from vault/ideas/, vault/tasks/, vault/inbox/, vault/research/ (via the index — don't brute-force). Focus on:

• action_required: true
• status: New
• priority: p0_urgent or p1_important
• Anything with no follow-up yet

Then add a Cross-Stream Opportunities pass: ideas in one stream that could feed another (e.g., "side-project metrics → content material", "day-job learnings → learning-stream progress").

Step 2: For Each Item — Draft or Research

If vault context is sufficient:

Search the vault for related notes, then draft a proposal:

• Save to vault/drafts/YYYY-MM-DD-title.md
• Frontmatter: type: draft, source_item: [path], status: active
• Keep it direct — 1 page max, lead with the recommendation

If external research is needed:

Write a deep-research prompt for whatever research tool the owner uses (an LLM deep-research mode, or the agent's own web search). Make it specific:

• What exactly to research
• Expected deliverables (comparison table, market size, pros/cons)
• Constraints that matter (budget, timeline, stack)

Save to vault/drafts/YYYY-MM-DD-research-prompt-title.md with type: research-prompt, status: pending-approval, source_item: [path]. Then ask:

Research needed for "[title]":
[1-line summary of what and why]

Prompt ready → vault/drafts/[file]

Options:
1. I run it now with my own web search
2. You paste it into your preferred deep-research tool — here's the prompt

Cost rule: prefer the owner's existing subscriptions and the agent's built-in search over metered APIs. Never call a paid API for research without asking.

Step 3: When Research Comes Back

When the owner pastes results (or your own search completes):

1. Read the research output; if it's a substantial source, store the verbatim text in vault/raw/
2. Combine with vault context (related notes, past decisions)
3. Draft a final proposal → vault/drafts/ with type: draft, status: active
4. Show it for review

Step 4: Summary

Reasoning complete:

Drafted (ready for review):
- "Pricing approach for side project" → vault/drafts/YYYY-MM-DD-pricing-approach.md

Research queued (needs your approval):
- "Competitor scan for [topic]" → prompt in vault/drafts/YYYY-MM-DD-research-competitors.md

Skipped (not actionable yet):
- "Maybe explore a rewrite" — too vague, needs more context

Step 5: File Insights Back (Karpathy pattern)

When reasoning produces valuable connections or synthesis — don't just display them. Offer to file them back so knowledge compounds:

• Cross-stream connections → vault/notes/YYYY-MM-DD-connection-title.md
• Research synthesis → vault/research/YYYY-MM-DD-synthesis-title.md
• New concept pages (topic mentioned 3+ times) → vault/research/

Flow: identify outputs worth preserving → ask "File these back into the vault? [list]" → on yes, create the files with the full compile step (index row, wikilinks, tags, log line — CLAUDE.md rule 6).

Auto-apply without asking (additive, safe): index rows for new files, wikilinks between related pages discovered during reasoning, stream Activity Log rows.

---

Rules

• Draft in the owner's voice (see vault/SOUL.md Voice section and the draft skill's calibration).
• Don't re-process items that already have drafts or status != New.
• If an item is ambiguous, skip it and flag — don't guess.
• Every run appends a vault/log.md line: ## [YYYY-MM-DD HH:MM] reason | N drafted, N queued, N skipped