name: programming-stories-requirements description: "Generate concise, well-structured feature requirement documents for the Programming Stories Dashboard project. Use this skill whenever the user wants to plan, spec out, define, or document a new feature, enhancement, or change to the Programming Stories Dashboard — including changes to HackerNewsScraperService, ProgrammingStoriesApi, the Kafka pipeline, filtering logic, API endpoints, the in-memory store, or the Angular frontend integration. Trigger when the user says things like 'I want to add...', 'let's build...', 'I'm thinking of a feature...', 'write up requirements for...', or 'help me spec out...'. The output is a focused requirements doc purpose-built for handing to Claude Code in Plan mode."

Programming Stories Requirements Skill

Read ~/.claude/skills/requirements/SKILL.md and follow its workflow, output format, and quality guidance exactly. The Architecture Reference below replaces the generic architecture context in that skill — use it instead of asking the user about the codebase.

Architecture Reference

The project is a .NET 10 solution with two services and a Kafka backbone:

HackerNewsScraperService (source/HackerNewsScraperService/)

• Worker Service that polls HackerNews Firebase API every 60s
• ScraperService.IsProgrammingRelated() — keyword filter before publishing
• Publishes matching stories as JSON to Kafka topic programming-stories
• In-memory dedup with a HashSet<int> (capped at 1000 IDs)
• Config: Scraper:PollingIntervalSeconds, Scraper:MaxStoriesToProcessPerCycle

ProgrammingStoriesApi (source/ProgrammingStoriesApi/)

• ASP.NET Core Minimal API
• StoryConsumerService — background Kafka consumer that upserts into StoryStore
• StoryStore — thread-safe LRU-style in-memory store, capped at Store:MaxCount stories
• GET /api/stories?start=&end=&minScore= — filtered list, newest first
• GET /api/stories/{id} — single story by ID
• CORS configured for Angular frontend at http://localhost:4200

HackerNewsStory (defined in each project independently):

Id, By, Title, Url, Score, Time (unix epoch), Descendants, Type

Infrastructure: Kafka runs locally via Docker Compose (KRaft mode, localhost:9092)

Project-Specific Example

User says: "I want to add pagination to the stories endpoint."

Good requirements doc:

# Feature: Paginated Stories Endpoint

## Goal
The `/api/stories` endpoint currently returns all matching stories at once. Add cursor-based
pagination so the Angular frontend can load stories incrementally and reduce initial payload size.

## Affected Components
- `ProgrammingStoriesApi/Program.cs` — update `/api/stories` endpoint signature and response shape
- `ProgrammingStoriesApi/Services/StoryStore.cs` — add paginated query method

## Acceptance Criteria
- [ ] `GET /api/stories` accepts optional `cursor` and `limit` query parameters
- [ ] Response includes a `nextCursor` field (null when no more results)
- [ ] Default page size is 50, configurable via `Store:DefaultPageSize`
- [ ] Existing `start`, `end`, and `minScore` filters still work with pagination
- [ ] CORS policy requires no changes

## Constraints
- Use cursor-based (not offset) pagination to remain stable as new stories arrive
- Follow the existing Options pattern for configuration (bind via `builder.Configuration`)
- Do not break the existing `/api/stories/{id}` endpoint

## Non-Goals
- Frontend Angular implementation — this is API only
- Persistent storage or external caching
- Authentication or rate limiting

## Notes / Assumptions
- The cursor can be opaque to the client — encoding insertion order position is sufficient
- StoryStore's LinkedList order makes cursor-based pagination natural