Write an implementation plan with LingCode

If a task is a single edit — rename a function, fix a typo — you don't need a plan. If it's "wire OAuth across the iOS app, Android app, and the web," you do. The difference is where the cost of being wrong shows up.

Without a plan, ordering decisions get baked into the first file LingCode writes. You discover at step 8 that step 2 should have come last — and now you're either reverting eight commits or carrying around a half-broken codebase while you rework. Both are expensive.

A written plan does three things that pay back the time you spend writing it:

• Surfaces ordering assumptions. "Add the database column" before "ship the API that reads it" before "ship the UI that calls the API." When you write it down, the dependencies become obvious — and sometimes you realize the order you had in your head was backwards.
• Names the riskiest step. Every multi-step task has one step where the project lives or dies — the migration, the third-party integration, the schema change. Naming it explicitly lets you do it first, when reversing is cheap, not last when it's a Friday-night roll-back.
• Gives you a contract to run against. When LingCode is executing the plan, you can compare what it did to what the plan said. Drift becomes visible. Without a plan, "drift" is just "what LingCode happened to do."

Write a plan when:

• The task touches three or more files and isn't a mechanical refactor.
• It crosses a layer boundary — DB + API + client, or iOS + Android + server.
• It involves an irreversible step — schema migration, third-party integration, data backfill, public API change.
• You can't picture all the changes in your head at once.

Don't write a plan when the task is genuinely one edit. Planning a one-line fix is procrastination dressed up as engineering.

A plan is only as good as the spec it's planning. If you haven't run the brainstorm pass — clarified scope, listed requirements, sketched a design — do that first. See Brainstorm before you build.

The brainstorm output is the input to the plan. When you ask LingCode for a plan, paste in (or reference) the requirements list and design sketch. Planning against "add OAuth" gives you a generic plan. Planning against "add Google OAuth to the iOS app and Android app, sharing one Firebase project, with email/password kept as a fallback for users who already have accounts" gives you a useful one.

Prompt LingCode to write a plan file, not a chat message. A file is reviewable, diff-able, and can be referenced later when execution drifts:

Don't write code yet. Write IMPLEMENTATION_PLAN.md in the repo
root.

Structure:
1. Goal — one sentence.
2. Non-goals — bulleted list of things explicitly out of scope.
3. Steps — numbered, each step in this format:
   - What changes (files touched, what they do after).
   - Why this step is ordered here (what depends on it,
     what it depends on).
   - How we verify it works before moving on.
4. Riskiest step — name the single step where the project is
   most likely to break, and why.
5. Rollback plan — what we revert if step N fails. Per-step
   where it matters, otherwise one sentence at the end.

Aim for 6-12 steps. If it's more than 12, the task is too big
and should be split. If it's fewer than 3, it doesn't need a
plan — just do it.

The "riskiest step" section is the one most people skip. It's also the one that pays back the planning time. Knowing in advance which step can sink the project means you can do it first, when you're fresh and the rest of the work hasn't been committed yet.

When LingCode hands you the plan file, don't accept it. Read it like a reviewer. Ask:

• Is the goal sentence the right goal? If it drifted off the brainstorm intent, fix it now.
• Are non-goals complete? The point of the non-goals section is to prevent scope creep mid-execution. If something could be in scope and you've decided it's not, write it down.
• Does each step's "why ordered here" hold up? If a step's justification is "no particular reason," the order can change later for free — but flag that you noticed.
• Is the riskiest step honest? If LingCode named "rename a function" as the risk, you didn't get a real risk assessment. Push back: "what's actually most likely to go wrong here?"
• Does verification exist for each step? "Run the tests" is fine if there are tests. "Looks right" is not verification.

Once you've identified the riskiest step, ask LingCode to reorder the plan so it comes early:

The OAuth provider integration is the riskiest step. Reorder
the plan so it happens before the iOS UI work and before the
Android UI work — both can be stubbed until we know the
integration works end-to-end.

Move it to step 2 (after the brainstorm-confirming exploration
in step 1). Adjust dependencies accordingly. Update the
verification for step 2 to be "can complete a real OAuth round
trip in a test app."

You won't always be able to put the risky step first — sometimes it has hard dependencies. Get it as early as those dependencies allow. The principle: if this step fails, you want to know on day one, not day five.

Re-read the "how we verify it works" line on every step. The plan is only honest if each step has a real check. Replace anything fuzzy:

• "Works correctly" → "Returns 200 on the happy-path test and 401 on a missing-token test."
• "Looks right" → "Screenshot of the new screen matches the design sketch within the standard tolerance."
• "Tests pass" → "xcodebuild test -scheme MyApp exits 0 with no new failures."

Vague verification is how plans turn into "well, it looked done." Tightening this now means execution checkpoints (next tutorial) have something to actually check.

Commit the plan file to your repo as its own commit, separate from any code. Two reasons:

• It's there for reviewers. When someone reviews the PR that comes from this work, they can see the plan you intended to follow.
• It's there for LingCode. When you pick this work back up tomorrow (or the day after), the plan file is the context that gets you back into the shape of the task in thirty seconds instead of thirty minutes.

git add IMPLEMENTATION_PLAN.md
git commit -m "Add implementation plan for OAuth migration"

Now you're ready to execute. The next tutorial covers running the plan one step at a time with checkpoints — the half that turns a plan from a doc into an outcome.

Package the planning workflow as a skill so LingCode triggers it on multi-step work:

---
name: writing-plans
description: Use when you have a spec or requirements for a multi-step task, before touching code. Triggers: 'plan this', 'write an implementation plan', 'how should I approach this multi-step task', 'design doc', complex task with >3 steps, spec / requirements input. Actions: produce IMPLEMENTATION_PLAN.md with goal, non-goals, 6-12 ordered steps each with per-step verification, explicit riskiest step (put first), rollback plan. Output: reviewable plan file. Anti-patterns: ordering-by-dependency-only (risky-first beats dependency-first), unverified steps, no rollback.
---

Write an implementation plan to IMPLEMENTATION_PLAN.md before
writing any code.

Structure the file:
1. Goal — one sentence.
2. Non-goals — bulleted list of out-of-scope items.
3. Steps — 6-12 numbered steps. Each step has:
   - What changes (files, new behavior).
   - Why ordered here (dependencies, what it unblocks).
   - How to verify before moving on (specific commands or
     observable outcomes, not "looks right").
4. Riskiest step — name the single step most likely to fail
   and why. Move it as early in the order as dependencies
   allow.
5. Rollback plan — what to revert if a step fails.

After writing the plan, stop and wait for review. Don't start
implementing. Apply requested edits to the plan file, not to
code.

If the task naturally needs more than 12 steps, split it into
multiple plan files for sequential delivery rather than one big
plan.

Save as ~/.lingcode/skills/writing-plans/SKILL.md — see Install a skill for the exact location and how skills get discovered.

Get LingCode →