[paulinevos]

Summary

Make hot-topic recaps explain the underlying situation or event instead of cataloguing individual posts. Add php artisan headlines:refresh to regenerate current hot-topic recaps immediately without waiting for the scheduled job or the two-hour reuse window.

This is separate from the Hot topics UI PR and targets upstream production directly.

Changes

• Ask the writer for one or two short sentences, aiming for at most 300 characters, led by the main development and its most important supporting detail. Avoid post-by-post framing, generic reactions, tangents, and filler about absent disagreements. Retain uncertainty, grounding, privacy, and prompt-injection safeguards. The existing 600-character hard validation limit is unchanged.
• Run the refresh command synchronously for the current hot-topic shortlist, reusing the normal usefulness check, source selection, locks, and publication checks. It refreshes recaps, not headline classification or names.
• Keep the existing recap until a useful replacement is ready. Provider failure or abstention does not erase it. Publication verifies that the original recap timestamp and source bodies have not changed during generation.
• Leave scheduled generation and its normal two-hour reuse behavior unchanged. Update the public knowledge base's description of recap style.

Validation

• php artisan test --compact tests/Feature/Commands/RefreshHeadlineSummariesTest.php tests/Unit/Jobs/GenerateHeadlineSummaryTest.php tests/Unit/Jobs/GenerateHotHeadlineSummariesTest.php tests/Unit/Services/HeadlineProviders/OpenAIHeadlineProviderTest.php — 67 passed, 213 assertions. Covers immediate replacement of fresh recaps, missing recaps, cold/no topics, abstention, competing updates, source changes, sanitized failures, existing scheduled reuse, and provider contracts.
• composer test:lint, composer test:types, composer test:type-coverage, and bun run test:unit — all passed. Type coverage is 100%; JavaScript unit tests: 222 passed. Existing non-failing lint warnings remain in unchanged files.
• php -d memory_limit=-1 vendor/bin/pest --parallel --ci --coverage --exactly=100.0 --passthru-php="'-d' 'memory_limit=-1'" — 5,455 passed, 29,314 assertions, 100% coverage.
• php artisan headlines:refresh --help confirms command registration and synchronous-refresh description.
• No UI markup, styles, or interactions change; visual/device verification is inapplicable to this backend/CLI/prompt change.

Independent review

PASS, no blocking findings, from independent read-only review of exact base e557d66c → head 976f420e. Review covered the complete five-file diff, surrounding code/tests, user intent, concurrency/invalidation, privacy, architecture, and meaningful coverage. Visual/device review is inapplicable to this backend/CLI/prompt-only diff.

The reviewer inspected the targeted-test and JavaScript logs but did not rerun tests. Full PHP coverage was pending at review time; its final outcome is reported above. No live-provider style evaluation was performed.

Limitations

• Provider tests use fakes. The revised writing style has not been evaluated against a live AI provider; a passing suite verifies orchestration, not generated prose quality.
• The 300-character target is prompt guidance, not a new hard cap. Existing recaps are unchanged until refreshed or regenerated after expiry.
• An already-running generator holds the shared per-topic lock; overlapping refresh attempts coalesce rather than generating concurrently. Provider failure stops the command with a sanitized exception; earlier completed topic updates are retained.
• No production refresh or deployment was performed. Hosted CI is separate from local checks.

Summary by CodeRabbit

• New Features
  • Hot-topic recaps can now be refreshed, including generating recaps for topics that don’t yet have one.
  • Recaps are kept unchanged when source information changes during generation or a replacement can’t be produced.
• Documentation
  • Recap guidance now emphasizes explaining the underlying event in one or two short sentences rather than listing individual posts.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

The recap prompt and documentation now focus on concise descriptions of underlying events. A new command refreshes summaries for current hot topics, and the summary action checks for headline or source changes before publishing.

Changes: Headline Recap Refresh

Layer / File(s)	Summary
Recap content instructions app/Ai/Agents/HeadlineSummaryWriter.php, KNOWLEDGE_BASE.md	The prompt requests a one- or two-sentence recap of up to 300 characters that focuses on the event and supporting detail. The documentation describes recaps as explanations of the underlying situation or event.
Refresh and publication checks app/Actions/CreateHeadlineSummary.php	handle accepts an optional refresh flag that bypasses the age limit when enabled. Before publication, the action checks that the headline still exists, its summary timestamp is unchanged, and its source bodies match those summarized.
Hot-topic refresh command app/Console/Commands/RefreshHeadlineSummariesCommand.php, tests/Feature/Commands/RefreshHeadlineSummariesTest.php	headlines:refresh regenerates summaries for current hot headlines and wraps generation errors with the headline ID. Tests cover replacement, skipped publication, empty results, and failures.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant RefreshHeadlineSummariesCommand
  participant HotHeadlinesQuery
  participant CreateHeadlineSummary
  participant HeadlineSummaryWriter
  RefreshHeadlineSummariesCommand->>HotHeadlinesQuery: Select current hot headline IDs
  RefreshHeadlineSummariesCommand->>CreateHeadlineSummary: Handle each ID with refresh enabled
  CreateHeadlineSummary->>HeadlineSummaryWriter: Generate recap
  HeadlineSummaryWriter-->>CreateHeadlineSummary: Return recap
  CreateHeadlineSummary->>CreateHeadlineSummary: Check timestamp and source bodies before publication

Loading

Possibly related PRs

• dev-null-sh/dev-null.sh#1391: Adds the CreateHeadlineSummary action extended by this change.
• dev-null-sh/dev-null.sh#1392: Displays hot topics and their stored recaps.
• dev-null-sh/dev-null.sh#1389: Adds the hot-headline query used to select recaps for refresh.

Suggested reviewers: mnapoli, nunomaduro

Merge Risk: Low · up to 976f4

A refresh may report success without updating every hot-topic recap. The existing recap remains available, and the command can be rerun; this is a bounded merge risk.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

[Copilot]

🟢 Approval recommended

No active review issues were identified for the recap and refresh-command changes.

No open issues 🎉

What changed in this PR

Updates the backend hot-topic recap pipeline to produce concise, event-focused briefs and lets operators refresh current recaps immediately without changing the scheduled two-hour reuse behavior.

Changes:

• Revises writer guidance toward one or two short sentences, targeting 300 characters while retaining existing safeguards.
• Adds synchronous headlines:refresh, preserving existing recaps until a replacement passes publication checks.
• Adds refresh-command tests and updates the public recap documentation.

File	Description
tests/​Feature/​Commands/​RefreshHeadlineSummariesTest.php	Tests refresh behavior, conflicting updates, abstention, and sanitized failures.
KNOWLEDGE_BASE.md	Documents the event-focused recap style.
app/​Console/​Commands/​RefreshHeadlineSummariesCommand.php	Adds synchronous refresh for the current hot-topic shortlist.
app/​Ai/​Agents/​HeadlineSummaryWriter.php	Refines instructions for concise, grounded briefs.
app/​Actions/​CreateHeadlineSummary.php	Supports forced refresh and checks recap timestamps and sources before publication.

_{Review effort: Balanced}