ISSUES.md

Format reference

ISSUES.md format: simple, human-first, and scalable

ISSUES.md is a single Markdown file you can read in 5 seconds, edit anywhere, and review in git diffs. The format is intentionally small: predictable sections, stable IDs, and status markers that match how humans think about work.

See the format Open the app

Format at a glance

Every issue is one list item. Everything else is optional, but structured so it stays readable as the file grows.

One issue entry
- [ ] [B042] (P1) {I007} Short title
  Optional body lines are indented by two spaces.

The parts of the first line

[ ], [x], [!]
Status: open, resolved, blocked.
[B042]
Canonical ID (section letter + 3 digits).
(P0), (P1), (P2)
Priority (optional).
{I007,B003}
Dependencies (optional).
Title
Short, human-readable summary. Start with a verb.

Sections and identifiers

Issues are grouped under level-2 headings. IDs must match the section they live in.

  • B BugFixes
  • I Improvements
  • M Maintenance
  • F Features
  • P Planning

Numbers are three digits (001 to 999) and increment per section.

Status markers

  • [ ] Open (unresolved)
  • [x] Resolved (done)
  • [!] Blocked (unresolved)

Blocked issues

If an issue is marked [!], include a Blocked: explanation in the body. 

- [!] [B123] (P0) Fix crash on startup
  Blocked: waiting on upstream API access.

Body text

Add details on new lines. Indent by two spaces to keep them attached to the issue. 

- [ ] [I010] Improve onboarding copy
  ### Summary
  Make the setup steps obvious.

Why this format works

Human-centric

  • Readable without tools
  • Fast to edit in any text editor
  • Works offline

Git-native

  • Small diffs: one line changes the status
  • Stable IDs for links and references
  • Reviewable in code review

Agent-friendly

  • Clear structure to parse
  • Dependencies are explicit
  • Body text stays attached to its issue

Scales without ceremony

  • Categories keep the file navigable
  • Three-digit IDs keep numbering consistent
  • Optional fields keep the format simple

Copy-paste templates

Start with the smallest thing that works. Add priority, dependencies, and bodies only when they help.

Minimal
- [ ] [B001] (P1) Fix the thing that is broken
  Context and repro steps go here.
Blocked
- [!] [I002] (P1) Add OAuth onboarding
  Blocked: waiting on GitHub client credentials.
With dependencies
- [ ] [F010] (P0) {I002,B001} Add onboarding wizard
  Keep the first version small; iterate from usage.
Resolved
- [x] [M010] (P2) Document the branching model
  Resolved: docs updated and linked from the UI.