From Chaos to Shipped — A Practical Workflow for Solo Developers

If you’ve ever ended a coding session unsure what you actually finished, switched between projects and lost your train of thought, or deployed something only to realize you forgot to set an environment variable — this guide is for you.

I built this workflow to solve my own problems. Context-switching between projects was killing my focus, and half my best ideas were disappearing before I could act on them. I needed a system that would protect my creative momentum — not just track tasks, but give me enough structure to stay loose and keep building. What came out of that is a four-phase workflow I now use daily.

Solo development is uniquely hard. There’s no standup to force clarity, no PR reviewer to catch the obvious, no project manager tracking what’s in flight. The chaos isn’t a character flaw. It’s a systems problem, and systems problems have systems solutions.

This guide walks through the four phases — Capture → Plan → Build → Ship — designed around tools you’re probably already using: a text editor, GitHub, and a bit of Markdown. No new apps required.

The four phases at a glance

Phase 1: Capture

The first place chaos enters is the moment an idea strikes. Most developers either ignore it (gone by morning) or immediately start building (hello, scope creep). The Capture phase gives you a third option: a frictionless landing spot that doesn’t interrupt what you’re currently working on.

The IDEA.md file

Keep a single IDEA.md per project — or one global backlog. When a thought surfaces, drop a one-liner:

- [2025-03-14] [QuizQuest]  add breadcrumb nav to lesson view
- [2025-03-14] [BAK EOS]    auto-fill shift date from system clock
- [2025-03-15] [QuizQuest]  dark mode toggle in settings

No polish. No planning. Just capture. The goal is to stop losing ideas to context, not to evaluate them in the moment.

Weekly triage

Once a week — end of Friday works well — go through IDEA.md and run each item through three questions:

1. Which project does this belong to?
2. What’s the rough size — an hour, a day, or a sprint?
3. Is this worth a GitHub issue? If yes, create one and delete the line. If no, delete it anyway.

An idea that can’t survive a 10-second triage wasn’t worth building.

Turning an idea into a GitHub issue

Every real work item lives in GitHub. When something survives triage, open an issue using a consistent template. At minimum:

• What you’re building and why (one or two sentences)
• What’s explicitly in scope
• What’s explicitly out of scope — this is the most important line
• A definition of done: how will you know it’s complete?
• A task checklist: the individual steps you’ll take

Label the issue (feat, fix, chore, docs), assign it to a milestone if timing matters, and link it to your project board. The issue is now the single source of truth for that work item — your planning doc, task list, and history all in one.

Why this matters: Most solo dev chaos traces back to work that exists only in someone’s head. GitHub issues externalize your intent. When you context-switch, get interrupted, or return to a project after two weeks away, the issue tells you exactly what you were building and why.

Phase 2: Plan

Planning feels like overhead until you’ve spent three hours building the wrong thing. The Plan phase is short by design: answer the questions that will otherwise derail you mid-build — before you start coding.

Write a feature brief

Before touching a branch, write two to four sentences directly on the GitHub issue:

• Goal: what the feature accomplishes, from the user’s perspective
• Scope: what’s included in this issue, specifically
• Non-goals: what’s explicitly deferred to later
• Done when: a concrete, testable condition

The non-goals line is the most important. Writing “not touching the notification system yet” prevents the 2am realization that you’ve rebuilt half the app to support something that wasn’t in scope.

Build a task checklist on the issue

GitHub issues support Markdown checkboxes. Use them. Break the feature into discrete tasks, each completable in a single session:

## tasks

- [ ] design Supabase schema for coach_sessions table
- [ ] write pgvector similarity search query
- [ ] build useCoach hook with API call
- [ ] wire hook to CoachPanel component
- [ ] add loading/error states
- [ ] smoke test with 3 real quiz attempts

This checklist serves three purposes: it’s your to-do list while building, a progress indicator visible on the issue, and a record of what actually shipped.

Cut the branch

Name branches with a consistent pattern: feat/42-socratic-coach-ui

Never work directly on main. The branch name alone should tell you what you were building and where to find the context.

Phase 3: Build

The Build phase is where the actual work happens, and where context gets lost. Two habits make the difference: disciplined commits and breadcrumb notes.

Conventional commit messages

Conventional commits make your git log readable, your diffs reviewable, and automated tooling possible. The format:

type(scope): short description

feat(coach): add pgvector similarity search
fix(auth): redirect loop on expired session token
chore: upgrade next to 15.2.1
docs(api): document /modules endpoint
feat(api)!: rename /lessons to /modules    # breaking change

Rules:

• Imperative mood: “add” not “added”
• 72 characters or fewer in the subject line
• One logical change per commit
• Reference the issue in the body: Closes #42

The breadcrumb habit

This is the single highest-leverage habit for multi-project solo development. Before closing your editor or switching projects, leave a note indicating exactly where you stopped and what comes next.

In the code:

// TODO: next — wire Supabase call in useCoach.ts
// Left off: schema works, hook needs error boundary

Or as a comment on the GitHub issue:

Pausing here. Completed: schema, pgvector query.
Next: build useCoach hook, then CoachPanel wiring.
Blocker: need to check Supabase RLS policy for coach_sessions.

The real cost of skipping this: Without a breadcrumb, returning to a project after even two days means 20–30 minutes of re-orienting: re-reading diffs, re-opening tabs, re-figuring out intent. Multiply that across three active projects and it’s a real tax on every session.

Draft PRs as checkpoints

For features spanning multiple sessions, open a draft pull request early. It gives you a visual diff of everything committed so far, a comment thread for notes and decisions, and a psychological anchor — the work is in progress, not in limbo.

Prefix the title with [WIP] or use GitHub’s native Draft PR feature. Convert to ready when all checklist items on the issue are ticked.

Phase 4: Ship

Shipping is where most solo projects fumble — not because the code is wrong, but because the surrounding process gets skipped. A five-minute pre-deploy check prevents the 11pm “why is production broken” investigation.

PR self-review before merging

Read your own diff before merging. Before you hit merge, verify:

• The linked GitHub issue will be closed by this merge
• All checklist items on the issue are ticked
• No console.log, debug code, or commented-out blocks remain
• Any changed behavior is reflected in docs or CHANGELOG
• The PR description explains the change for future reference

Merge via squash to keep main history clean. One feature, one commit on main.

The deploy checklist

Run through a checklist before every production push. For a Next.js + Supabase stack:

⚠️ Critical order: Always run database migrations before deploying the application code that depends on them. Deploying first creates a window where new code runs against the old schema — this is the most common source of production incidents in small Next.js + Supabase projects.

The retro note

After every deploy, write one sentence in RETRO.md:

2025-03-14 QuizQuest — deploy failed: migrations not run before push. Add to checklist.
2025-03-10 BAK EOS   — .env var missing in Vercel; caught it in smoke test.
2025-03-05 QuizQuest — feature took 3x longer: scope wasn't locked. Write the brief first.

Review RETRO.md monthly. When the same note appears three times, you have a process problem worth fixing at the root. These compound into real improvements over time.

Files to keep in every project

The quick-reference cheat sheets

Here’s the commit message reference card — keep it open in a tab until the format is second nature:

feat(scope): add thing          # new feature
fix(scope): correct thing       # bug fix
chore: update thing             # no prod code change
docs(scope): document thing     # docs only
refactor(scope): reshape thing  # no behavior change
feat(scope)!: rename thing      # breaking change

And branch naming:

feat/42-socratic-coach-ui
fix/38-auth-redirect-loop
chore/51-upgrade-next
docs/55-api-endpoint-reference

Wrapping up

This workflow is intentionally minimal. It lives entirely in GitHub and a couple of Markdown files you can drop into any project in under a minute. No new tools, no subscriptions, no onboarding.

I built it because I was tired of losing momentum between sessions and watching good ideas evaporate. Using it consistently gave me back creative space I didn’t realize I’d lost — fewer “where was I?” mornings, more time actually building.

The habits that move the needle most, in order:

1. Breadcrumb notes — the fastest fix for context-switch pain
2. Feature briefs with non-goals — the fastest fix for scope creep
3. The deploy checklist — the fastest fix for production incidents
4. RETRO.md — the slowest fix, but the one that compounds

Start with one. Add the others as the pain point it solves becomes real.

Grab my free interactive workflow diagram, commit cheat sheet, deploy checklist, and other helpful resources here.