Stale Detection & Nudge System

Decisions

• Pending: What are the default stale thresholds per lifecycle status?
• Pending: How many nudges before auto-escalation to review?
• Pending: Should auto-advance/cancel rules require user confirmation or fire autonomously?
• Pending: Nudge delivery channel — dashboard only, briefing, or push (Telegram)?

User Tasks

---

Summary

Track how long feature requests stay in the same status without progress, surface stale items through nudges, and optionally auto-advance or auto-cancel based on configurable rules.

Problem / Motivation

Feature requests can silently stall — sitting in “in-progress” for weeks or “new” indefinitely with no one noticing. Without active stale detection:

• FRs accumulate in limbo, cluttering the backlog
• Blocked items are never surfaced unless manually reviewed
• There is no pressure to move work forward or close abandoned items
• The feature lifecycle looks active on paper but is actually stagnant

Inspired by Sven’s Nexus system, which uses rules like “deliver + waiting > 2h = auto-advance” and “review + waiting > threshold = auto-cancel” to keep work flowing. A stale detection system turns the passive FR lifecycle into an actively managed pipeline.

Proposed Solution

Build a stale detection engine with three layers:

1. Detection Layer

• Track time-in-status for every FR by comparing updated frontmatter date with current date
• Configurable thresholds per status:
  • new > 14 days = stale
  • planned > 21 days = stale
  • in-progress > 7 days without commits = stale
  • Thresholds stored in a config file (e.g., src/opus/stale/config.yaml)
• Detection runs as part of daily briefing or on-demand via skill

2. Nudge Layer

• Surface stale items in dashboards with a “stale” badge/flag
• Include stale items in daily briefing (FR-037) as a dedicated section
• After N nudges without action, escalate: move to a “needs review” flag or notify via Telegram (FR-022)
• Nudge counter tracked per FR (in frontmatter or separate state file)

3. Auto-Action Rules

• Configurable rules engine for automatic status transitions:
  • deliver + waiting > 2h → auto-advance to done
  • review + waiting > threshold → auto-cancel or move back to planned
  • new + stale > 30 days → move to ideas (de-prioritize)
• Rules defined in config, each with: trigger condition, action, requires-confirmation flag
• All auto-actions logged in FR history

---

Open Questions

1. Default Stale Thresholds

Question: What should the default time-in-status thresholds be?

Option	Description
A) Conservative	new: 14d, planned: 21d, in-progress: 7d. Forgiving, fewer false alarms
B) Aggressive	new: 7d, planned: 14d, in-progress: 3d. Forces fast movement
C) User-configurable from day one	No defaults, user must set thresholds in config

Recommendation: Option A — start conservative to avoid alert fatigue. Tighten thresholds based on experience.

Decision:

2. Nudge Escalation Count

Question: How many nudges before escalating a stale FR?

Option	Description
A) 1 nudge, then escalate	Aggressive — forces immediate action
B) 3 nudges over 3 days	Balanced — gives the user time to act
C) 5 nudges over a week	Patient — minimal pressure

Recommendation: Option B — three daily nudges strikes a balance between visibility and annoyance.

Decision:

3. Auto-Action Safety

Question: Should auto-advance/cancel rules require user confirmation?

Option	Description
A) Always require confirmation	Safe — no surprises. Auto-actions become suggestions
B) Configurable per rule	Some rules auto-fire (low-risk), others need confirmation
C) Fully autonomous	All rules auto-fire. Fast but risky

Recommendation: Option A for Phase 1. Move to Option B in Phase 3 once trust is established.

Decision:

---

Phase Overview

Phase	Description	Status
Phase 1	Detection logic + dashboard surfacing	—
Phase 2	Push nudges via briefings and Telegram	—
Phase 3	Auto-advance/cancel rules engine	—

---

Phase 1: Detection Logic + Dashboard Surfacing —

Goal: Detect stale FRs based on configurable thresholds and surface them in dashboards/briefings.

File / Feature	Details	Owner	Status
src/opus/stale/detector.py	Stale detection engine — parse FR frontmatter, compare updated date vs thresholds	opus	—
src/opus/stale/config.yaml	Threshold configuration per status (new, planned, in-progress)	opus	—
Dashboard integration	Add “Stale” column/badge to feature dashboard	opus	—
Briefing integration	Add stale items section to daily briefing output (FR-037)	opus	—
Unit tests	Test detection with various FR ages and statuses	opus	—

---

Phase 2: Push Nudges via Telegram —

Goal: Deliver nudge notifications for stale FRs via Telegram and track nudge count.

File / Feature	Details	Owner	Status
src/opus/stale/nudger.py	Nudge manager — track nudge count per FR, send notifications	opus	—
Nudge counter	Track how many times each FR has been nudged (frontmatter field or state file)	opus	—
Telegram integration	Send nudge messages via Telegram bot (depends on FR-022)	opus	—
Escalation logic	After N nudges, flag FR for review with higher visibility	mv	—

---

Phase 3: Auto-Advance/Cancel Rules Engine —

Goal: Implement configurable rules that auto-advance or auto-cancel FRs based on conditions.

File / Feature	Details	Owner	Status
src/opus/stale/rules.py	Rules engine — evaluate conditions, trigger actions	opus	—
Rule definitions	Config format for rules: condition, action, requires-confirmation	mv	—
Auto-advance	Move FR forward in lifecycle when deliver+waiting exceeds threshold	opus	—
Auto-cancel	Move FR back to ideas or mark rejected when review+waiting exceeds threshold	mv	—
History logging	Log all auto-actions in FR history table with timestamp and rule that triggered	opus	—
Safety guards	Confirmation prompts for destructive actions, dry-run mode	mv	—

---

Prerequisites / Gap Analysis

Requirements

Requirement	Description
REQ-1	Python project scaffold (FR-009) — detection and rules are Python code
REQ-2	Daily briefings (FR-037) — nudges surface in briefing output
REQ-3	Phone/Telegram access (FR-022) — push nudges via messaging

Current State

Component	Status	Details
Python scaffold	—	FR-009 not started
Daily briefings	—	FR-037 not started
Telegram access	—	FR-022 not started
FR frontmatter	done	All FRs have status, updated fields
Feature dashboard	done	vault/00_system/dashboards/ exists

Gap (What’s missing?)

Gap	Effort	Blocker?
Python scaffold (FR-009)	Med	Yes — detection logic is Python code
Briefing system (FR-037)	Med	Partial — Phase 1 can work with dashboard only
Telegram bot (FR-022)	High	No — only needed for Phase 2 push nudges

---

Test

Manual tests

Test	Expected	Actual	Last
FR in-progress for 8 days detected as stale (7d threshold)	Marked stale	pending	-
FR in-progress for 5 days NOT detected as stale	Not marked	pending	-
Stale FR appears in dashboard with badge	Badge visible	pending	-
Nudge counter increments after each detection cycle	Count increases by 1	pending	-
After 3 nudges, FR is escalated	Escalation flag set	pending	-
Auto-advance rule fires for deliver+waiting > threshold	FR advanced to next status	pending	-
Auto-cancel with confirmation shows prompt before acting	Prompt displayed, action paused	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 stale detection and auto-advance/cancel rules

---

References

• FR-037 (Daily Briefings) — stale items surface in briefing output
• FR-022 (Phone Access) — push nudges via Telegram
• FR-031 (Workflow State Machine) — auto-advance/cancel rules interact with state transitions
• FR-050 (Proactive Monitoring) — stale detection is a subset of vault consistency monitoring
• FR-039 (Priority Scoring) — stale items receive priority boosts
• Nexie (Sven Hennig) — original inspiration for stale detection and auto-action rules