Who this is for
Developers about to refactor who want a controlled plan, not a half-migrated mess they lose track of partway through.
The moment this saves you
I start a refactor with a clear picture in my head, get three files deep, lose the thread, and end up with a half-migrated mess that's worse than what I started with and risky to ship.
See it work
Messy spoken thought in. A clean, structured artifact out.
Planning a refactor. The problem is our API routes are all giant functions with the validation, business logic, and database stuff all mixed together, it's untestable and every change is scary. The target is to split each into three layers, a thin route handler, a service layer for logic, and a repository for data access. The safe way to do this, I'll start with the most isolated route, the one with no shared dependencies, prove the pattern there, write tests, then migrate the rest one route at a time, never more than one in flight. The risk is touching the shared user service, that's used everywhere, save that for last and do it carefully. I do not want a big-bang rewrite, incremental only.
Refactor plan, June 5, 2026
- Problem: API routes are giant functions mixing validation, business logic, and data access. Untestable; every change is risky.
- Target state: Split each into three layers, thin route handler, service layer (logic), repository (data access).
- Safe step order:
1. Start with the most isolated route (no shared deps), prove the pattern, write tests 2. Migrate the rest one route at a time, never more than one in flight 3. Save the shared user service (used everywhere) for last, do it carefully
- Constraint: Incremental only, NO big-bang rewrite
The workflow
Record a voice note
Hit the hotkey and talk, no formatting, no typing.
Tag it with this context
Contextli shapes your words into the structured output above.
Find it later
Everything's searchable and organised by context.
Pull it into Claude or ChatGPT
Bring your contexts straight into your AI tools with the Contextli MCP.
Your raw recording and transcription stay on your device, so you can always go back to the original.
The prompt behind this context
I'm going to talk through a refactor I'm planning. Turn it into a refactor plan: a bold "Refactor plan, [today's date]" heading, then labeled parts: **Problem** (what's wrong with the current code), **Target state** (the desired structure), **Safe step order** (a NUMBERED list of the migration steps in the order I describe, preserving which to do first and last and why), and **Constraint** (any rule I set, e.g. incremental only). Keep my technical reasoning and ordering exactly. Don't invent steps or risks I didn't raise. Output only the plan.
Make it your own. This is a starting point. Once it's in Contextli, tweak the instructions so the output comes out exactly how you like it.
Use this context
One click copies it and shows you exactly how to drop it into Contextli.
Next, open Contextli, go to the Contexts page, click Import, choose From JSON, paste, then Import Context. It is ready to use.
Make it your own. This is a starting point. Once it's in Contextli, tweak the instructions so the output comes out exactly how you like it.
Your raw recording and transcription stay on your device, so you can always go back to the original.
Related contexts
Technical Spec Note
You've figured out the approach in your head and writing the spec feels like a tax. Talk it through, the problem, the approach, the tradeoffs, the open questions. You get a structured skeleton you can flesh out, instead of staring at a blank design doc.
Code Decision Log
Right after you make the call, while the tradeoffs are still fresh, talk through why you went this way and what you rejected. Three months from now when someone asks 'why a queue here?', the answer is already written down.
Learning Log
You finally figure out that tricky thing, a flag, a pattern, a gotcha, and three weeks later you're googling the exact same thing. Say what you learned and the context. You build a searchable log of your own hard-won lessons, so you only have to learn each one once.
Questions people ask
Questions developers ask about Refactor Plan Note
What should a refactor plan include?
A good refactor plan includes a clear title, steps to reproduce the issue, the expected behavior, the actual behavior observed, the severity or priority, and the environment details such as OS, browser, and app version. The Refactor Plan Note context structures your spoken description into these fields automatically, so nothing gets left out when you are in the middle of debugging.
How do I write a refactor plan in under a minute?
Speak what you found: describe the issue, what you expected, what actually happened, and how bad it is. The Refactor Plan Note context structures your words into a complete refactor plan you can paste directly into Jira, Linear, or GitHub Issues. Most take under 60 seconds to dictate, so you capture them without breaking your flow.
How do developers capture issues without interrupting their flow?
The key is to capture the issue immediately without switching context mentally. Contextli lets you speak a quick voice note describing it and produces a refactor plan from it. You can dictate while the issue is still on screen, then paste the formatted output into Jira, Linear, or GitHub Issues when you come up for air. No typing is required during the capture step.
Can I write a refactor plan by talking instead of typing?
Yes. The Refactor Plan Note context lets you speak a description in plain language and converts it into a structured refactor plan with all the required fields filled. You speak the way you would explain it to a colleague, and the context handles the formatting.
How do I add this context to Contextli?
Copy the context on this page, then open Contextli and go to the Contexts page. Click Import, choose From JSON, paste it into the Import from Clipboard window, and click Import Context. It is ready to use in under 30 seconds. If you do not have Contextli yet, you can download it for free first.
Is my voice recording private? Does Contextli send it anywhere?
Your voice recording and the transcription are stored on your device only. Contextli processes your audio locally and does not send your recordings or transcription text to any server. The structured output it produces is text you control, and you decide where it goes.
Can I change what the output looks like?
Yes. Every context in Contextli is a starting point you can edit. Open the context in the app, change the instructions to adjust the structure, tone, or fields, and save. The next time you use it, the output reflects your changes. You are not locked into the default format.
Do I need to install an app to use this context?
Yes. Contextli is a free app. Download it, then copy this context and paste it into the Import from Clipboard window on the Contexts page. The whole process takes about 30 seconds.