Decisions
- Pending: Monitoring frequency — hourly, daily, or event-driven?
- Pending: Which external sources to scan first? (GitHub releases, RSS, Reddit)
- Pending: Pitch delivery channel — terminal only, vault inbox, or messaging?
- Pending: Auto-create FRs on approval, or just add to inbox for manual processing?
- Pending: Self-improvement scope — can the system modify its own code, or only propose changes?
User Tasks
Summary
Build a proactive monitoring system that detects pain points, patterns, inconsistencies, and external events — then automatically proposes actionable improvements through a structured pitch flow.
Problem / Motivation
Currently Opus is entirely reactive — it only acts when the user initiates work. This means:
- Recurring errors go unnoticed until they cause visible failures
- Repetitive manual patterns are never identified for automation
- External events (new Claude releases, dependency updates) are missed
- Vault inconsistencies (stale FRs, missing references, broken links) accumulate
- The system only improves when the user thinks to improve it
Nexie solves this with a proactive monitoring layer that continuously scans for opportunities and pain points, then proposes solutions through a lightweight pitch flow. This transforms the system from a tool the user operates into a partner that actively identifies work worth doing.
Proposed Solution
Build a Python monitoring module with multiple detection strategies, all feeding into a unified pitch pipeline:
Detection Strategies
1. Error Log Analysis
- Monitor agent failure logs, git hook errors, skill execution errors
- When the same error appears 3+ times, auto-create a pitch
- Example: “Agent X failed to parse FR format 4 times this week → pitch: standardize FR parsing”
2. Vault/Spec Consistency Checks
- Periodically scan the vault for inconsistencies:
- FRs referencing non-existent dependencies
- Features in-progress with no recent commits
- Dashboard counts out of sync with actual files
- Broken internal links between vault files
- Templates diverging from actual FR format usage
- Example: “FR-043 has been in-progress for 2 weeks with no commits. FR-040 references a dependency that doesn’t exist.”
3. Pattern Detection from Usage
- Track which tasks the user performs repeatedly
- If the same manual sequence occurs 3+ times, recognize the pattern and propose automation
- Example: “You’ve manually updated the feature dashboard 5 times this week. Propose: auto-sync dashboard on FR status change.”
4. Internet Monitoring
- Monitor specific external sources for relevant information:
- GitHub releases for Claude Code, dependencies, tools
- RSS feeds for relevant tech news
- Reddit threads for community insights
- When actionable information is found, create a pitch
- Example: “Claude Code v1.5 released with new agent features → pitch: review changelog and create FRs for relevant upgrades”
5. Self-Improvement Loop
- The system proposes features that make the system better
- If agent execution is slow, propose optimization
- If specs frequently need revision, propose better templates
- Track improvement velocity and suggest meta-improvements
- The recursive aspect: the monitoring system monitors itself
Pitch Pipeline
The trigger-to-action flow:
- Monitoring job runs on schedule (configurable frequency)
- Analyzes logs, usage patterns, vault state, external sources
- Detects something worth acting on
- Creates a pitch — a concise Problem → Proposal message
- Delivers pitch to user via preferred channel
- User approves/rejects with a single reply
- If approved, enters the standard feature workflow (creates FR, enters lifecycle)
Pitch Template:
[PITCH] Source: {error-log | vault-scan | pattern | internet | self-improvement}
Problem: {one sentence}
Proposal: {one sentence}
Evidence: {data supporting the pitch}
Action: approve / reject / defer
Open Questions
1. Monitoring Frequency
Question: How often should the monitoring system run?
| Option | Description |
|---|---|
| A) Hourly | Catches issues fast, but high resource usage. Useful for error monitoring |
| B) Daily | Balanced — runs once per day (e.g., during briefing generation). Good for vault scans |
| C) Event-driven | Triggered by specific events (git commit, session start, error threshold). Most efficient |
| D) Mixed | Error monitoring event-driven, vault scans daily, internet checks on schedule |
Recommendation: Option D — different strategies warrant different frequencies. Error monitoring should be event-driven (fast), vault scans daily (thorough), internet checks configurable.
Decision:
2. External Sources
Question: Which external sources should be monitored first?
| Option | Description |
|---|---|
| A) GitHub releases only | Most actionable — Claude Code updates directly affect Opus |
| B) GitHub + RSS feeds | Broader coverage, more noise to filter |
| C) GitHub + RSS + Reddit | Full coverage, requires good relevance filtering |
Recommendation: Option A — start with GitHub releases for Claude Code and key dependencies. Expand based on value delivered.
Decision:
3. Pitch Delivery Channel
Question: How should pitches be delivered to the user?
| Option | Description |
|---|---|
| A) Vault inbox | Write to vault/90_inbox/. User sees in Obsidian. No external deps |
| B) Terminal notification | Show during next Claude Code session. Immediate but ephemeral |
| C) Messaging (iMessage/WhatsApp) | Push notification. Requires FR-023. Most visible |
Recommendation: Option A — vault inbox is persistent and review-friendly. Terminal notification as supplement. Messaging later.
Decision:
4. Auto-Create vs Suggest
Question: When user approves a pitch, should the system auto-create an FR or just add to inbox?
| Option | Description |
|---|---|
| A) Auto-create FR | Full automation — approved pitch becomes FR immediately |
| B) Add to inbox for manual processing | User reviews and decides placement. Safer |
| C) Auto-create draft FR | Creates FR in new/ but marks as draft for user review |
Recommendation: Option C — auto-create a draft FR so the user doesn’t have to start from scratch, but still reviews before it enters the workflow.
Decision:
Phase Overview
| Phase | Description | Status |
|---|---|---|
| Phase 1 | Error log monitoring | — |
| Phase 2 | Vault/spec consistency checks | — |
| Phase 3 | Pattern detection from usage | — |
| Phase 4 | Internet monitoring + self-improvement loop | — |
Phase 1: Error Log Monitoring —
Goal: Detect recurring errors across agent runs, hook failures, and skill executions.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
src/opus/monitoring/collector.py | Log collector: aggregate errors from git hooks, agent outputs, skill logs | opus | — |
src/opus/monitoring/analyzer.py | Error pattern analysis: count occurrences, group by type, detect repeats | opus | — |
src/opus/monitoring/pitch.py | Pitch generator: create structured pitch from detected pattern | opus | — |
| Error threshold config | Configurable: how many occurrences before generating a pitch (default: 3) | opus | — |
| Log storage | Where to persist collected logs (append-only log file or SQLite) | opus | — |
| Unit tests | Error detection, threshold triggering, pitch generation | mv | — |
Phase 2: Vault/Spec Consistency Checks —
Goal: Periodically scan the vault for inconsistencies, stale items, and broken references.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
src/opus/monitoring/vault_scanner.py | Vault scanner: walk vault files, parse frontmatter, check references | opus | — |
| Dependency validation | Check that FR prerequisites reference existing FRs | opus | — |
| Stale detection | Find FRs in-progress with no git activity for X days | opus | — |
| Dashboard sync check | Verify dashboard counts match actual file counts per status | mv | — |
| Broken link detection | Find internal vault links ([[...]]) that point to non-existent files | opus | — |
| Template drift detection | Compare actual FR format usage against _templates/feature-request.md | opus | — |
| Pitch generation | Create pitches for each category of inconsistency found | opus | — |
Phase 3: Pattern Detection from Usage —
Goal: Identify repetitive manual patterns that could be automated.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
src/opus/monitoring/usage_tracker.py | Track user actions: which skills invoked, which files edited, which sequences repeated | mv | — |
| Sequence detection | Identify repeated action sequences (3+ occurrences of same pattern) | opus | — |
| Automation proposals | Generate pitches proposing automation for detected patterns | opus | — |
| Privacy considerations | Only track action types, not content. User opt-in for detailed tracking | mv | — |
| Integration with session logs | Parse Claude Code session history for action patterns | opus | — |
Phase 4: Internet Monitoring + Self-Improvement Loop —
Goal: Monitor external sources for relevant updates and enable recursive self-improvement.
| File / Feature | Details | Owner | Status |
|---|---|---|---|
src/opus/monitoring/internet.py | External source scanner: GitHub releases, RSS feeds | opus | — |
| GitHub release monitoring | Check Claude Code and dependency releases, compare with current versions | opus | — |
| Relevance filtering | Score external information for relevance to Opus before creating pitches | opus | — |
| Self-improvement analysis | Monitor system performance metrics: agent success rate, task duration, pitch acceptance rate | opus | — |
| Meta-improvement proposals | Propose improvements to the monitoring system itself based on effectiveness data | opus | — |
| Recursive improvement tracking | Log which self-improvement proposals were accepted and their measured impact | opus | — |
Prerequisites / Gap Analysis
Requirements
| Requirement | Description |
|---|---|
| REQ-1 | Python project scaffold (FR-009) — monitoring module is Python code |
| REQ-2 | Workflow state machine (FR-031) — for auto-creating FRs from approved pitches |
Current State
| Component | Status | Details |
|---|---|---|
| Python scaffold | — | FR-009 not started |
| State machine | — | FR-031 not started |
| Error logging | — | No centralized error collection exists |
| Self-improvement log | done | vault/00_system/logs/self-improvement-log.md exists (manual) |
Gap (What’s missing?)
| Gap | Effort | Blocker? |
|---|---|---|
| Python scaffold (FR-009) | Med | Yes — monitoring is Python code |
| Centralized log collection | Med | No — can be built in Phase 1 |
| External API access | Low | No — GitHub API is public, RSS is standard |
| State machine for FR creation (FR-031) | High | Partial — Phase 1-2 can work without it |
Test
Manual tests
| Test | Expected | Actual | Last |
|---|---|---|---|
| Dashboard sync check finds mismatch | Mismatch reported with actual vs expected counts | pending | - |
AI-verified tests
| Scenario | Expected behavior | Verification method |
|---|---|---|
| … | … | … |
E2E tests
| Scenario | Assertion |
|---|---|
| … | … |
Integration tests
| Component | Coverage |
|---|---|
| … | … |
Unit tests
| Component | Tests | Coverage |
|---|---|---|
| … | … | … |
History
| Date | Event | Details |
|---|---|---|
| 2026-03-04 | Created | Inspired by Nexie’s proactive monitoring and auto-trigger capabilities |
References
- FR-009 (Python Project Scaffold) — code infrastructure prerequisite
- FR-049 (Error Logging & Notification) — error logging feeds into monitoring
- FR-048 (System Self-Review) — manual version of what this automates
- FR-066 (Self-Improving System) — broader self-improvement vision; this FR is a concrete implementation path
- FR-031 (Workflow State Machine) — state machine enables auto-FR-creation from approved pitches
- FR-037 (Daily Briefings) — monitoring findings can feed into daily briefings
- Nexie (Sven Hennig) — original inspiration for proactive monitoring architecture