# Daily Brief Signal Quality Implementation Source

## Status

- Date: 2026-05-19
- Source type: discussion-to-implementation-doc
- Status: ready for implementation planning
- Recommended plan:
  `docs/plans/daily-brief-signal-quality/daily-brief-signal-quality-plan.md`
- Recommended execution state:
  `docs/plans/daily-brief-signal-quality/daily-brief-signal-quality-execution-state.md`

## Purpose

Improve the `topic-radar` and `daily-brief` workflow so low-engagement
GitHub/HN items can remain useful as early watchlist material without being
overpromoted into the daily brief topline. Preserve the feedback loop in the
Heuristic System so repeated reporting corrections become skill policy, tests,
and compact operation evidence rather than hidden model memory.

## Triggering Example

The 2026-05-18 daily brief promoted GateGraph as a leading developer signal
because `topic-radar` ranked a very fresh HN item highly. Follow-up inspection
showed the item was low engagement:

- Raw source path:
  `/Users/terry/Project/graysurf/daily-brief/raw/2026/05/2026-05-18-ai-tech-news.json`
- Source: `hn.algolia.com`
- Object ID: `48176270`
- HN reason: `1 points, 0 comments`
- URL: `https://github.com/humancoreai/Gategraph`
- Live GitHub inspection during discussion: 2 stars, 0 forks

This information was still useful as a topic sample for agent governance, but
it should have been labeled as low-signal early watchlist context rather than a
topline item.

## Confirmed Facts

- `topic-radar` currently ranks by source weight, engagement, recency, topic
  match, and cross-source duplication.
- `topic-radar` already includes HN points/comments in the reason string, but
  it does not expose normalized HN metrics or GitHub repository metrics for HN
  items that link to GitHub repositories.
- `fetch_github` filters direct GitHub search results with `stars:>10`, but HN
  or news items can still link to low-star repositories.
- `daily-brief` consumes `topic-radar --format json` and must not reimplement
  source fetching, cache, RSS/API parsing, or ranking.
- `daily-brief` currently tells agents to lead with high-signal bullets, but it
  does not define high-signal thresholds or watchlist placement rules.
- `HEURISTIC_SYSTEM.md` defines the loop for promoting workflow lessons into
  skills, scripts, tests, runbooks, evidence records, and guardrails.
- `skill-usage` is the released nils-cli primitive for deterministic skill
  usage evidence. Agent-kit owns record policy, promotion, compression, and
  serial-write discipline.

## Decisions

- Keep low-star and low-HN-engagement items in the report when they add useful
  topic context, but classify them as `early-watchlist`.
- Do not let `recency + topic match` alone qualify an item for Topline.
- `topic-radar` owns normalized metrics, source-strength classification, and
  `signalTier` assignment.
- `daily-brief` owns presentation: Topline should use high/medium signals;
  low-signal items should move to `Early Watchlist` with visible metrics.
- Do not record every routine daily brief as a retained skill-usage artifact by
  default. Record correction events, validation runs, and implementation
  outcomes when they materially improve skill behavior.
- Keep deterministic writing and schema validation in the nils-cli
  `skill-usage` primitive. Do not build a second record writer in agent-kit.

## Scope

- Add signal-quality metadata to `topic-radar` JSON and Markdown output.
- Add optional public GitHub repository metadata enrichment for GitHub URLs that
  enter through HN or news items.
- Add a `signalTier` model that distinguishes high-signal, medium-signal, and
  early-watchlist items.
- Update `daily-brief` skill instructions to use signal tiers and to show
  watchlist metrics explicitly.
- Add focused tests and sample fixtures for a GateGraph-like low-star HN item.
- Add compact Heuristic System guidance for recording user correction feedback
  and compressing it into skill/test changes.

## Non-Scope

- Do not add paid news, GitHub auth, browser scraping, posting, trading, or
  credentialed actions.
- Do not turn `daily-brief` into a source fetcher or ranking engine.
- Do not remove low-signal items entirely; the target behavior is demotion and
  labeling, not suppression.
- Do not change routine daily-brief record storage in personal record
  repositories.
- Do not implement primitive-level locking or schema changes in nils-cli unless
  later evidence proves the current `skill-usage` primitive is insufficient.

## Requirements

- A low-star GitHub repository linked from a low-engagement HN item is marked
  `early-watchlist`.
- Early-watchlist items remain available in JSON and Markdown output with
  visible metrics and reasons.
- Brief clusters and daily synthesis do not treat early-watchlist items as
  topline material.
- Official releases, mainstream coverage, cross-source items, and materially
  engaged community/open-source items can still qualify as high or medium
  signal.
- The scoring note continues to warn that heuristic score is triage, not
  objective importance.
- The Heuristic System feedback loop can capture this correction as a compact
  operation record after implementation and validation.

## Acceptance Criteria

- `topic-radar --sample --preset ai-news --format json` includes stable
  `signalTier` and `signalMetrics` fields.
- A GateGraph-like fixture with HN 1 point, 0 comments, GitHub 2 stars, and no
  cross-source duplication is classified as `early-watchlist`.
- Topline/brief cluster output excludes or clearly separates early-watchlist
  items.
- `daily-brief` docs instruct agents to put low-signal items in
  `Early Watchlist` with metrics rather than promoting them to Topline.
- Tests cover the new tier behavior, GitHub URL enrichment fallback, and
  daily-brief wording rules.
- A retained operation record or equivalent curated evidence summarizes the
  correction, durable policy change, and validation results after the fix lands.
