theam / theam/facility

Find a story by number or title from the Stories board

Open
#104 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement good first issue help wanted type:feature
Dominant language
TypeScript
Stars
71
Forks
64
Avg merge
15h 38m
Merged PRs (30d)
66

Description

The problem

The Stories board has exactly one filter: the seven stage chips (apps/web/app/(app)/projects/[projectId]/stories/page.tsx:78-110). To reach a specific story you scroll a board that renders every open story in the project, grouped into seven collapsible sections. There is no way to type a number, or a few words of a title, and land on it.

The ⌘K palette does not help. It navigates to sections — projects, stories, sessions, approvals, settings (apps/web/components/shell/cmdk.tsx:29-79) — and its own docstring says verbs and objects "join as surfaces land". Stories are a surface that has landed.

What I propose

A filter box on the board, filtering the already-fetched pipeline client-side on number, title, repository and assignee. api.pipeline(projectId) (stories/page.tsx:41) already returns every visible story with all of those fields, so this is a client component over data in hand: no request, instant feedback per keystroke, and it composes with the stage chips rather than replacing them.

And a number that jumps. When the query is a bare number (912 or #912), offer go to story #912 as the first result and navigate to /projects/{id}/stories/912?repoId=… on Enter.

That second half matters because of a real boundary. /pipeline returns open stories plus those shipped in the last seven days (assembleProjectStories, services/api/src/routes/v1/github.ts:987), so a filter over the board cannot reach an older closed story — while the story endpoint resolves any number in the mirror (assembleSelectedStories, :1051). Typing a number should therefore work regardless of the window; typing words honestly cannot, and the empty state should say "not on the board — older stories are searchable by number" rather than imply the story does not exist.

With several connected repositories the jump needs a repoId. When the number is not on the board, either resolve without one and let the endpoint's 409 (ambiguous_story_number) drive a repository picker, or offer one entry per repo up front.

Then feed the palette. Once the board has a matcher, ⌘K gaining story #N / title entries for the current project is the same predicate reused — and that is the answer to "from anywhere, take me to that story".

What I considered instead

  • A server-side search endpoint. The right long-term answer for full history — gh_issues is already indexed on (org, project, gh_updated_at) and a trigram index on title would be cheap — but it is not what makes the common case fast. The story you are looking for is almost always on the board, and the board is already in memory.
  • Filtering through the URL, like the stage chips. A round trip per keystroke for data the client already holds. A stage chip is a link because it is a shareable view; a search box is not.

Related: #18, #39. Findings are against 5712bf8.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in apps/web/app/(app)/projects/[projectId]/stories/page.tsx, especially the pipeline data and stage-chip rendering, then read apps/web/components/shell/cmdk.tsx. Trace api.pipeline(projectId) and the story routes at services/api/src/routes/v1/github.ts:987 and :1051, including repository ambiguity. Done means board filtering works with the existing chips, numeric queries can reach any story, and the same matcher supports current-project palette entries.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
frontend, search
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.