Keep an Issue List Instead of Your Brain. A Build Next Stack field guide for learners shipping small projects.
One tracker, zero heroic memory
Solo builders treat mental backlogs as free until a bug resurfaces three weeks later with no repro notes. Alex moved everything actionable to GitHub Issues—or GitLab, Linear, a single markdown file in repo—one home, searchable, with dates. The rule: if it takes more than two minutes and is not tonight’s task, it gets an issue before the tab closes.
Capture speed beats taxonomy. Title first: Upload fails on Safari 17 mobile. Body template:
- Seen — when and where
- Expected vs actual — one line each
- Repro steps — numbered, even if partial
- Guess — optional, labeled as guess
Brains are for thinking; issues are for storage.
Labels that fit in one glance
Alex uses at most six labels: bug, feature, chore, blocked, good-first, wontfix-yet. No label sprawl—if you debate tag color, you are procrastinating.
Priority is not a label; it is milestone or week field. This week milestone holds three issues max. More than three means scope fantasy; cut or defer explicitly.
Close issues aggressively with comment when wontfix: Duplicate of #42 or Out of scope for v1 personal use. Open issue count is a mood metric; lie to yourself with forty opens and you stop opening the tracker.
Issues vs notes vs README
Not everything belongs in issues. Reference docs, architecture decisions, setup steps—README or docs/. Issues hold work units with a finish line. Alex’s test: Can I close this with a merge commit? Yes → issue. No → doc or comment on existing issue.
Epics get one parent issue with checklist child issues—or a single issue with markdown checkboxes if children feel heavy. Parent without children becomes a vague wish; split until each checkbox is one evening.
Weekly triage in twenty minutes
Every Sunday Alex runs triage:
- Close stale duplicates and things already fixed accidentally.
- Move at most three issues to This week milestone.
- Add repro steps to any bug that lacks them— or close as cannot reproduce until it returns.
- Label blocked items with who or what blocks—waiting on DNS propagate.
Timer twenty minutes. Triage is scheduling, not solving. Solving happens on weekdays against the three picks.
Link commits and issues without ceremony
Commit messages reference issues: fix #17 upload timeout on slow 3G. GitHub auto-closes with keywords; even plain reference preserves traceability. Alex avoids fix without number—archaeology returns.
PR descriptions for solo work still matter: screenshot, test note, closes #17. Future you reads PRs when bisecting regressions.
When the list lives in markdown instead
No Git host? Single ISSUES.md in repo with sections Open and Done. Move lines on commit; date stamp when opened. Search with editor or grep. Less convenient than GitHub but versioned alongside code—better than Apple Notes graveyard.
Rule stays: one file, one format, weekly triage. Tool choice matters less than never trusting memory for repro steps.
Emotional backlog hygiene
Issue trackers become guilt museums. Alex schedules a quarterly wontfix purge: close old feature wishes with kindness—Still like this, but not for 2026 scope. Open count drops; motivation returns.
Celebrate closes visibly: changelog line or README recent fixes. Solo work lacks standup applause; a closed issue list is the standup.
Alex pins the open This week milestone on phone home screen widget—three titles visible without opening laptop. Visibility beats good intentions stored only on desktop.
Templates that make filing faster than skipping
GitHub issue templates live in .github/ISSUE_TEMPLATE/—bug and feature with prefilled sections. Alex spends twenty minutes once; every report after saves typing repro headers. Feature template asks Why now? to kill nice-to-have noise.
Bug template includes Can you ship without this fix? checkbox—forces honest severity. Urgent unchecked items wait; checked yes may defer to backlog without guilt.
Mobile capture: send yourself email with subject issue: upload timeout safari and body repro; triage Sunday moves to tracker. Inbox is not the tracker—Sunday conversion is mandatory.
Metrics that stay lightweight
Alex tracks two numbers weekly: open issue count and issues closed. Trend matters more than absolute. Rising opens with flat closes means scope creep or capture without triage. Target slow decline or stable low teens for hobby scale.
Do not import enterprise velocity metrics—story points cosplay solo. One closed user-visible fix beats five reorganized labels.
Monthly screenshot of milestone board archived in docs/progress/ optional; useful when portfolio writeup time arrives and memory lies about pace.
When an issue grows beyond one evening, split into sub-issues with clear done states—parse CSV separate from render chart. Large issues linger and distort open count psychology.
Integration with git and changelog
Closing issue #24 should appear in changelog same release. Alex adds Closes #24 in PR body and copies title to changelog bullet. Traceability from user report to release note helps when someone asks did you fix the Safari bug yet.
Reopened issues get comment explaining why—regression, incomplete fix, new repro. Silent reopen looks like churn; comment preserves narrative.
Issue titles are user-visible in release notes sometimes; write titles that read well outside tracker context.
Alex exports open issues to markdown backup monthly—GitHub outage rare but issue list is project memory. Backup lives in private repo or encrypted drive, not public gist.
Stale issues without activity sixty days get ping comment: still relevant? Close if no reply in two weeks. Gentle decay prevents tracker becoming museum of abandoned ideas you feel guilty opening.
Capture issues from phone via GitHub mobile when idea strikes walking—body can be one sentence; triage adds structure Sunday. Speed of capture beats perfect formatting at keyboard later.
Searching closed issues before filing new saves duplicates—upload safari query takes five seconds and often finds open root cause already tracked.
File the next bug before closing the tab
Next time you notice something broken, open an issue before fixing it—or immediately after with repro while fresh. One habit pass this week beats migrating to a fancier tool.
Cap This week at three issues. A honest short list ships; a heroic mental list stalls.
Your brain is for solving problems, not holding them. The tracker remembers so you can sleep.