Epictetus
13221f2019
- GitHub excluded from feed (with silent-revert caveat) - Score-floor tiering replaces percentile gates - UPDATE text label dropped (color-only tier 2) - Headline cap raised to 300 (ceiling, not target)
90 lines
5.3 KiB
Markdown
90 lines
5.3 KiB
Markdown
# Decision Log
|
|
|
|
Records key architectural decisions for the Personal Agent OS.
|
|
|
|
## 2026-06-20: Initial Repo Structure
|
|
|
|
**Decision:** Created `personal-agent-os` as a single repo under `Tony_tech` org with `projects/`, `knowledge-base/`, `archive/`, `templates/`, `agent-config/`, and `_meta/`.
|
|
|
|
**Rationale:**
|
|
- Single repo over multiple repos: easier for Hermes to search_files across everything, simpler cross-referencing between projects and knowledge
|
|
- `archive/` over deletion: git history preserves everything, but active views stay clean
|
|
- `_meta/` at root (not under kb): repo-wide conventions and decision log should be immediately discoverable
|
|
- No auto-generating tag index in a folder: better to rebuild via cron script periodically
|
|
|
|
**Migrated from:** `Tony_tech/research/hermes-automation/` into `knowledge-base/automation-blueprints/hermes/`
|
|
|
|
**Trade-offs accepted:**
|
|
- Single repo means one default branch; projects share tag space (mitigated by hierarchical dir names)
|
|
- Cron scripts stored in two places: local disk (runs from) and repo (documentation). Must keep in sync.
|
|
|
|
## 2026-06-20: Daily Brief — Script + Context-From Pattern
|
|
|
|
**Decision:** Replaced agent-driven web/X search data gathering with a no-agent shell script that fetches free public APIs (wttr.in, HN Firebase, GitHub API).
|
|
|
|
**Why:** web_search and x_search were silently failing (Firecrawl unconfigured, xAI credits exhausted). The brief was returning `[SILENT]` for weeks.
|
|
|
|
**Result:** Working brief in <5 minutes, zero API costs, reliable data every tick.
|
|
|
|
**Cron job ID:** e94447937052
|
|
## 2026-07-12: GitHub Excluded from AI News Daily Feed
|
|
|
|
**Decision:** GitHub repos are excluded from the AI News Daily site feed (`generate_from_athena.py`). Athena still ingests them into `oracle.db` for research; the site generator filters them out.
|
|
|
|
**Rationale:**
|
|
- GitHub entries (repo releases, model cards) are tool announcements, not news events
|
|
- They dominated the feed due to high star-velocity scores (GLM-5.2, DeepSeek-R1, etc.)
|
|
- A "Breaking" tag on a repo release violates the editorial rule: repos/papers are never breaking
|
|
- GitHub was silently reappearing in the feed at least once this week despite prior exclusion — root cause not conclusively identified (possibly a reverted patch, config drift, or manual override)
|
|
|
|
**Implementation:** `generate_from_athena.py` filters `source IN ('github', 'gitlab', 'huggingface', 'arxiv')` → renders as plain links or drops entirely. This is a runtime filter, not a pipeline-level exclusion — Athena's DB still has the data.
|
|
|
|
**Trade-offs accepted:**
|
|
- Some genuinely interesting repos won't appear on the site (acceptable — site is for news, not discovery)
|
|
- If GitHub exclusion is ever reversed, it requires an explicit commit + decision-log entry, not an ad-hoc patch
|
|
|
|
**Trade-offs accepted:**
|
|
- Root cause of the silent revert is not conclusively identified; this entry documents the symptom and the fix, not a proven cause
|
|
|
|
## 2026-07-12: Score-Floor Tiering Replaces Percentile Gates
|
|
|
|
**Decision:** AI News Daily tiering (breaking/update/normal) uses absolute score floors + rank, not percentile cutoffs. A tier is allowed to be empty if nothing qualifies.
|
|
|
|
**Rationale:**
|
|
- Previous system: `BREAKING_PCT = 0.90` (top 10%), `UPDATE_PCT = 0.75` (next 25%) — this guaranteed something always appeared in each tier regardless of quality
|
|
- Result: 6 red + 15 green items in a single run because rank alone forced items into tiers
|
|
- New system: `min_score` floor per tier; if nothing clears the bar, the tier is empty
|
|
- Tiers must reflect editorial quality, not statistical inevitability
|
|
|
|
**Implementation:** `config.yaml` defines `tiering.breaking.min_score` and `tiering.update.min_score`. Generator script reads these at runtime. Floors set from real score distribution analysis (see score distribution in oracle.db).
|
|
|
|
**Trade-offs accepted:**
|
|
- Some runs may have zero "Breaking" items — this is correct behavior, not a bug
|
|
- Score floors require periodic review as the score distribution evolves
|
|
|
|
## 2026-07-12: "UPDATE" Text Label Dropped (Color-Only for Tier 2)
|
|
|
|
**Decision:** Tier 2 (update) items render in green (`#34a83d`) without a "UPDATE | " text prefix. Breaking items retain "Breaking | " prefix.
|
|
|
|
**Rationale:**
|
|
- "UPDATE | " prefix was visually noisy and implied a correction/follow-up relationship that doesn't exist for most tier-2 items
|
|
- Green color alone provides sufficient visual distinction from normal (black) and breaking (red)
|
|
- Pending a real replacement label if one emerges from editorial review
|
|
|
|
**Trade-offs accepted:**
|
|
- Without a text label, tier-2 distinction is color-only (accessibility trade-off, acceptable for this audience)
|
|
|
|
## 2026-07-12: Headline Cap Raised to 300 (Ceiling, Not Target)
|
|
|
|
**Decision:** `MAX_ITEMS` raised from 40 to 300. This is a hard ceiling, not a target — actual count drops via decay, score floors, and source filtering.
|
|
|
|
**Rationale:**
|
|
- Previous cap of 40 was arbitrary and too low for a 24h freshness window
|
|
- The real constraint is quality (score floor), not count
|
|
- 300 provides headroom for high-signal days while preventing runaway output
|
|
- Stories that don't meet the score floor are dropped regardless of count
|
|
|
|
**Trade-offs accepted:**
|
|
- A very high-signal day could theoretically produce 100+ items — editorial review needed if this happens regularly
|
|
- The cap is a safety valve, not a design target
|