How to start an issue without spiralling
A guide for my grad friends
The Situation
You’ve read this issue five times. It still makes no sense.
It’s labelled good first issue. Cool. Sure. Absolutely.
So… how do you ask for help without sounding like a donkey?
You don’t. Looking stupid is inevitable. The trick is doing it faster—because good team members won’t let you stay stuck in the mud for long.
Step 1: Understand the What.
Imagine your hut in the swamp has a leak, and sludge is pouring in, fast.
You’ve got two tools:
a bucket
a wad of mud and reeds.
Your first instinct:
Grab the bucket and start bailing.
You start scooping. It’s hard work, but it technically makes sense… sludge is filling the hut, so getting it out should help, right?
And you’d be right... kind of.
Here’s the catch:
The bucket is a correct solution to part of the problem. It addresses the symptom: the sludge filling the hut. We could call this solution an anti-pattern.
What’s an anti-pattern? An approach to solving a problem that, while appearing effective initially, ultimately leads to negative consequences or inefficiencies.
But it’s not the full picture.
The real what is:
The hut is sinking into the bog.
You’re not just fighting sludge, you’re fighting time. No matter how much you bail, if the leak keeps pouring sludge in, you’re still losing your swamp. Until you name the real problem, every fix is just damage control.
It’s common to come across solutions that are technically correct but not necessarily the most appropriate. As you iterate through solutions, it helps you realise what the actual problem is.
Step 2: Understand the Why.
So, why does it matter that the hut is sinking?
The why is simple:
So you still have a home when help arrives.
That’s the bigger picture, the motivation behind solving the problem.
With the why in mind, you can decide whether to keep bailing (short-term fix), patch the leak with mud and reeds (longer-term fix), or maybe do something else entirely.
Without the why, you’re just bailing sludge forever… and the hut still sinks.
Checkpoint: Do you understand the issue?
The what gets you writing code.
The why gets you owning problems.
| What’s normal | What can happen (but shouldn’t) | What good could look like |
| You read the issue 5 times and still don’t get it | Issues don’t explain why the problem matters | The issue explains both what’s broken and why it matters, with examples |
| You feel silly asking “basic” questions just to understand it | Issues try to solve 3 different problems at once | The issue is focused on one clear problem, with a clear “done” definition or victory condition |
Step 3: Check If the What Matches the Why
If the why is “to improve application load times” but the what is “refactor the outhouse comments”, something doesn’t add up.
When the dots don’t connect, stop and ask. Worst case? You feel a little silly for five seconds. Best case? You close an irrelevant ticket and clean up the backlog. Either way, that’s a win.
Step 4: Does It Say How?
(Spoiler alert: It probably doesn’t. It also usually doesn’t, so I won’t bother covering what to do if it does.)
Let’s skip to step 5.
Step 5: Now what?
Option A: Phone a Friend
The easy way out. Ask a trusted team member to walk you through how to solve the problem.
This feels like flipping to the back of your math textbook for answers.
Script if you feel awkward:
“Hey, I’m looking at [ticket name]—just want to check my understanding of the problem before I go too deep into the woods. Can I walk you through my thoughts, and you can correct me where I’ve gotten lost?”
Asking questions isn’t inexperienced behaviour. Experienced devs do it constantly, they’re just better at roaring XD for help faster.
Just like when flipping to the answers, it’s probably a good idea to reverse-engineer how you were supposed to end up there. Otherwise, it’ll be really embarrassing when your tech lead asks you how you solved a problem, and you go silent…
Option B: Investigate (But Timebox It)
This is the option I choose on days where I’ve woken up feeling especially resilient.
Toolbox Checklist — With a Flow:
Start with the issue itself.
→ Any clues? Key words that pop up frequently? Linked PRs? Comments? Related issues? Look for breadcrumbs.
Check the commit history.
→ Has anyone touched this file/problem area recently? What changed? Why?
Look in the codebase.
→ Search the name of the bug, function, component, or file in your codebase. Poke around and see what squishes.
Check internal docs.
→ Search the wiki, internal Confluence, README files, or API docs.
Zoom out to architecture.
→ Top-down: Look at the system diagram. What does this service/component do?
→ Bottom-up: Start from code you understand and work upwards until you connect it to the problem area.
Google shamelessly.
→ It’s okay if your questions look like “what is [internal acronym]” or “how does [framework] handle [concept].” You’d be surprised how often this works—even with internal stuff.
Timebox Reminder:
30 minutes max.
If you’ve got more than 10 tabs open and your eyes are glazing over, stop and ask.
I recommend still running your action plan by a team member, just to make sure you’re on the right track.
Checkpoint: Are you stuck, or just unsupported?
| What’s normal | What can happen (but shouldn’t) | What good could look like |
| Accidentally spending 30 minutes aimlessly poking around the codebase trying to connect the dots | No docs, no diagrams, no onboarding. Just vibes 💀 | A magic onboarding guide that says: “If you're working on X, start here, check this file, look at this diagram.” |
| Grepping random function names just to figure out where anything lives | Everyone’s “too busy” to help, so you’re left guessing if you’re even looking in the right place | Seniors casually DM: “Want me to sanity-check where you’re looking?” |
My Wrap-Up
If a ticket makes you feel stupid, that doesn’t mean you are. It just means the ticket doesn’t make sense yet.
You are allowed to:
Not know
Bang your head on your desk a couple times
Grab an iced oat matcha latte
Come back and try again
