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:

markdown
1# Feature: Paginated Stories Endpoint
2
3## Goal
4The `/api/stories` endpoint currently returns all matching stories at once. Add cursor-based
5pagination so the Angular frontend can load stories incrementally and reduce initial payload size.
6
7## Affected Components
8- `ProgrammingStoriesApi/Program.cs` — update `/api/stories` endpoint signature and response shape
9- `ProgrammingStoriesApi/Services/StoryStore.cs` — add paginated query method
10
11## Acceptance Criteria
12- [ ] `GET /api/stories` accepts optional `cursor` and `limit` query parameters
13- [ ] Response includes a `nextCursor` field (null when no more results)
14- [ ] Default page size is 50, configurable via `Store:DefaultPageSize`
15- [ ] Existing `start`, `end`, and `minScore` filters still work with pagination
16- [ ] CORS policy requires no changes
17
18## Constraints
19- Use cursor-based (not offset) pagination to remain stable as new stories arrive
20- Follow the existing Options pattern for configuration (bind via `builder.Configuration`)
21- Do not break the existing `/api/stories/{id}` endpoint
22
23## Non-Goals
24- Frontend Angular implementation — this is API only
25- Persistent storage or external caching
26- Authentication or rate limiting
27
28## Notes / Assumptions
29- The cursor can be opaque to the client — encoding insertion order position is sufficient
30- StoryStore's LinkedList order makes cursor-based pagination natural