Document issue title and description conventions

arne commented

2026-04-05 22:33:15 +02:00

Owner

PR #14 settled how pull request titles and descriptions should read, but issues were left unexamined. The current open backlog makes the gap concrete: every one of the four open issues uses an area prefix (design-system:, web:, project-detail:) followed by a telegraphic description that barely stands on its own as a sentence. That's exactly the pattern we moved away from for PRs, and for the same reason — the prefix is tagging noise a human reading the title doesn't need, and the Forgejo label system already handles area categorization better.

This PR extends CLAUDE.md with an Issue titles and descriptions subsection that applies the same discipline (active voice, plain English, no area prefixes) with one deliberate difference: tense. PR titles describe work done, issues describe work needed. The doc also calls out that issues are seeds, not specs — prose over bullets, a Scope section to bound what closing the issue looks like, and no pretense of being a specification.

Follow-ups

Rewrite the four open orbit issues (and the single closed one, #7) to match the new convention. This is the parallel of the historical-PR rewrite that followed the PR convention doc.
Add a history entry recording the issue rewrite once it's done.

PR #14 settled how pull request titles and descriptions should read, but issues were left unexamined. The current open backlog makes the gap concrete: every one of the four open issues uses an area prefix (`design-system:`, `web:`, `project-detail:`) followed by a telegraphic description that barely stands on its own as a sentence. That's exactly the pattern we moved away from for PRs, and for the same reason — the prefix is tagging noise a human reading the title doesn't need, and the Forgejo label system already handles area categorization better. This PR extends `CLAUDE.md` with an `Issue titles and descriptions` subsection that applies the same discipline (active voice, plain English, no area prefixes) with one deliberate difference: tense. PR titles describe work done, issues describe work needed. The doc also calls out that issues are seeds, not specs — prose over bullets, a `Scope` section to bound what closing the issue looks like, and no pretense of being a specification. ## Follow-ups - Rewrite the four open orbit issues (and the single closed one, #7) to match the new convention. This is the parallel of the historical-PR rewrite that followed the PR convention doc. - Add a history entry recording the issue rewrite once it's done.

arne added 1 commit

2026-04-05 22:33:15 +02:00

Document issue title and description conventions d37c1c51fe

Extend CLAUDE.md with an 'Issue titles and descriptions' subsection
alongside the existing PR conventions. The core discipline is the same
— active voice, plain English, no area prefixes like design-system: or
web: — but the tense differs because issues describe work needed rather
than work done. The doc also calls out that issues are seeds, not specs:
prose over bullets, a Scope section to bound what closing looks like,
and no pretense of being a specification. Specs come later via the
brainstorming flow when the issue is picked up.

arne force-pushed docs/issue-conventions from d37c1c51fe to c074cae828

2026-04-05 22:56:22 +02:00

Compare

arne merged commit b5e37eddcb into main

2026-04-05 22:56:50 +02:00

arne referenced this pull request from a commit

2026-04-05 22:56:51 +02:00

Document issue title and description conventions (#18)

Rows
Columns

Document issue title and description conventions #18

Follow-ups