Skip to main content
This document explains how work is tracked across Linear, GitHub, and the repo, in a way that stays clear and low-stress.

​
1. Tools

  • Linear: source of truth for tasks, features, bugs, and projects.
  • GitHub: source of truth for code, pull requests, and documentation.
  • Markdown: used inside issues and docs for checklists and lightweight planning.

​
2. Linear workflow

Each issue in Linear should:
  • Have a clear title (for example, FEATURE: Add basic CSV ingestion)
  • Use the correct issue type (Feature, Bug, Chore, Docs, Research)
  • Include a short summary, motivation, and acceptance criteria
  • Link to relevant docs or code

​
Statuses

Typical statuses in Linear:
  • Backlog: Not yet prioritized
  • Next: Selected for the upcoming sprint
  • In Progress: Currently being worked on
  • In Review: Pull request open / needs validation
  • Done: Merged and deployed
Sprints represent calm, focused 1–2 week periods of work.

​
3. Kanban / task conventions in Markdown

Use simple checklists inside Linear issues, GitHub issues, or docs: 
### Tasks

- [ ] Set up basic CSV ingestion
- [ ] Normalize transactions to internal model
- [ ] Render first dashboard view
- [ ] Add summary card for total weekly spend
For detailed implementation: 
### Implementation steps

- [ ] Define types for transactions
- [ ] Implement parser for FCIB CSV
- [ ] Write tests for parsing edge cases
- [ ] Connect parsed data to UI
Checklists keep progress visible without adding extra tools.

​
4. Linking between Linear and GitHub

  • Each pull request should reference a Linear issue.
  • Each Linear issue should link to:
    • GitHub pull requests
    • Related documentation files
    • Architecture notes or screenshots
This creates a calm, traceable history of why changes were made.

​
5. Progress rhythm

A calm week of engineering follows this pattern:

​
Start of sprint

  • Move 2–6 issues from Backlog → Next or In Progress
  • Confirm each issue has clear acceptance criteria
  • Update any relevant docs

​
During the sprint

  • Update issue statuses as work moves
  • Keep PRs small and easy to review
  • Split issues if they grow too large

​
End of sprint

  • Review completed work
  • Move unfinished items back to Backlog or Next
  • Update roadmap or product docs as needed
The goal is steady progress, not pressure.
Small rituals like this keep work grounded and predictable.