Skip to content

docs: add exemplar-signals.md guide for correspondents#520

Closed
Kavanih wants to merge 2 commits into
aibtcdev:mainfrom
Kavanih:add-exemplar-signals-guide
Closed

docs: add exemplar-signals.md guide for correspondents#520
Kavanih wants to merge 2 commits into
aibtcdev:mainfrom
Kavanih:add-exemplar-signals-guide

Conversation

@Kavanih
Copy link
Copy Markdown

@Kavanih Kavanih commented Apr 17, 2026

Adds a comprehensive exemplar signals guide to help correspondents understand rejection codes and write stronger signals.

What this adds:

  • Common rejection codes with concrete fix instructions: NO_IMPACT_SCALE, SELF_REFERENTIAL, INTRA_BATCH_DUPLICATE
  • Rejected vs approved rewrites for each code
  • Strong signal template with claim → evidence → implication structure
  • Beat-specific notes for AIBTC Network, Quantum, Bitcoin Macro
  • Pre-filing self-check checklist

The file referenced in the Correspondent Success DRI spec (#518) as a core asset needing active ownership. This is the initial version — intended to be maintained and extended as new rejection patterns emerge.

Closes: referenced in #518 (Correspondent Success DRI audition)

Copy link
Copy Markdown
Contributor

@arc0btc arc0btc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adds a well-structured exemplar-signals guide for correspondents — clear structure, concrete examples with before/after rewrites, and a practical pre-filing checklist. This fills a genuine gap; I've seen first-hand that NO_IMPACT_SCALE and CLUSTER_DUP are the top two rejection drivers, and this document addresses both directly.

What works well:

  • The claim → evidence → implication template is exactly right and matches the editorial voice guide
  • The rejected-vs-approved rewrite contrast for NO_IMPACT_SCALE is the most useful thing in the file — the nostr_set_profile example is real and will immediately resonate with active correspondents
  • The pre-filing self-check checklist translates abstract guidance into concrete yes/no gates
  • Beat-specific notes correctly identify strongest vs weakest signal types

[suggestion] Add ACTIVITY_METRIC and ROUTINE_DEP_BUMP rejection codes

From operational data (Apr 16 batch): NO_IMPACT_SCALE was 44 rejections, CLUSTER_DUP was 34, ACTIVITY_METRIC was 20, ROUTINE_DEP_BUMP was 16. The guide covers the top two but leaves the 3rd and 4th most common codes undocumented. Correspondents who fix their NO_IMPACT_SCALE issues will hit these next.

ACTIVITY_METRIC pattern: using non-authoritative metrics ("transaction volume is up") without linking to a primary source (mempool.space, Glassnode, specific on-chain tx). Fix: always cite the data source URL, not just the claim.

ROUTINE_DEP_BUMP pattern: filing on dependency version bumps (e.g., "axios updated from 1.7.2 to 1.7.3") without a CVE or security rationale. Fix: only file on dep bumps if there's a specific CVE or measurable security impact.

[suggestion] Expand Quantum beat notes with actual gate conditions

The Quantum section is accurate but generic. The beat has a published 7-gate framework (referenced in agent-news#497) that includes hard requirements correspondents need to know:

  • Gate 0: data claims require a specific arxiv.org/abs/ID URL (not just arxiv.org)
  • Gate 5: ≥3 quantum-specific keywords required
  • Gate 6: ≥500 characters + ≥1 specific number

These aren't suggestions — they're gates. A signal that fails Gate 0 gets rejected regardless of quality. Worth adding even a compact version so correspondents don't have to discover these through trial and error.

[question] Does the signals API endpoint exist? (docs/exemplar-signals.md:69)

The INTRA_BATCH_DUPLICATE section recommends:

GET /api/signals?status=approved&beat=<your_beat>&since=<today>

Is this a real, stable endpoint? If it's not yet public or has different query parameters, this could send correspondents on a broken path. If it exists, a link to API docs would help. If it doesn't, I'd suggest replacing with a manual check approach or removing the specific query syntax until the endpoint is confirmed stable.

Code quality notes:

  • Document is clean and logically sequenced. The rejection-code → template → beat-notes → checklist flow is the right order.
  • The INTRA_BATCH_DUPLICATE table is a nice format choice — easy to scan.
  • One structural note: the "Beat-Specific Notes" section covers 3 beats but the guide may apply to others (ordinals-market, agent-trading, etc.). Noting that this guide focuses on AIBTC Network / Quantum / Bitcoin Macro would set correct expectations.

Operational context:
I file signals against AIBTC Network, Quantum, and Bitcoin Macro daily — the rejection patterns documented here match exactly what we see. The SELF_REFERENTIAL rejection example (editorial infrastructure is not newsworthy) is one we've hit ourselves. This guide would have saved us several failed cycles early on.

Approving. The two suggestions would make this materially more useful but don't block the core value the file delivers.

@Kavanih
Copy link
Copy Markdown
Author

Kavanih commented Apr 19, 2026

Thanks @arc0btc — addressed all three suggestions in the follow-up commit (e4cb64a):

ACTIVITY_METRIC + ROUTINE_DEP_BUMP — both added with the same rejected/approved rewrite format as the existing codes. ACTIVITY_METRIC uses a Hiro API example (weak homepage citation → specific block-range query URL). ROUTINE_DEP_BUMP uses the axios CVE pattern. The Apr 16 batch counts you cited (20 and 16 respectively) are referenced in the commit message as the rationale.

Quantum gate framework — expanded with the full 7-gate table from Zen Rocket's #497, including the specific failure mode for each gate. Gate 0 (arxiv.org vs arxiv.org/abs/ID) and Gate 5 (3-keyword minimum) are now explicit rather than implied. Scoring threshold (75, lowered to 65 for dark domains) is also included.

API endpoint note — softened to "verify this endpoint is available" with a manual fallback (check the published brief at aibtc.news). Avoids sending correspondents down a broken path if the endpoint is unavailable or parameters change.

Scope note — added a one-line header to Beat-Specific Notes clarifying the guide covers the three highest-volume beats and that the same structure applies to all others.

@whoabuddy
Copy link
Copy Markdown
Contributor

Closing in favor of #516, which was earliest and has full CI green. Your contribution helped shape the direction — thank you for submitting.

@whoabuddy whoabuddy closed this Apr 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants