| 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):
- Read
vault/streams/{stream}.md for goals and context
- Consider only items with a matching
stream_id
- Draft proposals scoped to that stream's Active Goals
- 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):
- Read the research output; if it's a substantial source, store the verbatim text in
vault/raw/
- Combine with vault context (related notes, past decisions)
- Draft a final proposal →
vault/drafts/ with type: draft, status: active
- 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