| name | devlearn-before-you-ship |
| description | Pre-coding plain-English plan before large refactors or multi-file changes.
Use when >5 files will change, architecture shifts, new dependencies, or user
asks "what will you change before you do it". NOT the release checklist — use
devlearn-pre-ship before merge/deploy. Pairs with devlearn-teach-while-coding when
before_big_changes is true. Lifecycle: shared/ship-lifecycle.md. Voice triggers:
"plan first", "before you refactor", "what are you about to change".
|
DevLearn: Before You Ship (Plan)
Iron law
Plan in plain language; do not block small fixes. User says "go" → execute.
Voice
Follow ../shared/voice.md. No code dumps in the plan — filenames and intent only.
Context
This skill is pre-coding planning — before you edit files.
| Skill | When |
|---|
| before-you-ship (this) | Before writing code — scope, risks, verify |
| pre-ship | Before merge/release — tests, staging, rollback |
| deploy | Going live |
| post-ship | After URL exists — smoke tests |
Full chain: ../shared/ship-lifecycle.md
Vibers lose trust when agents touch ten files silently. Seasoned devs want scope and risk without a design doc novel.
Prerequisites
DEVLEARN.md optional; honor before_big_changes: true|false- Enough context to name files/areas (or ask one clarifying question)
When to invoke
| Trigger | Action |
|---|
before_big_changes: true and >5 files | Offer or run this skill |
| User: "plan first", "what will you change?" | Run |
| New dependency + restructure | Run |
| Architecture shift (auth, DB, routing) | Run |
| Single-file bug fix | Skip |
| User: "just ship" / "do it" | Skip plan; execute |
Meta skill (devlearn-teach-while-coding) should offer this automatically when thresholds hit.
Before you start
- Estimate file count and blast radius (grep/read structure)
- Read DEVLEARN.md persona — viber gets one term preview; seasoned gets decision framing
- Check if
/devlearn-pre-ship is what they meant ("ready to merge" → redirect)
Phase 1: Understand goal
Restate user outcome in one sentence — their words, not tech jargon.
If goal unclear, Status: NEEDS_CONTEXT — one question max.
Phase 2: Draft plan
Output shape:
## Before we change code
**Goal:** [user outcome in one sentence]
**What will change (plain English):**
1. [area/file group] — [intent]
2. ...
3. ...
**What we're NOT changing:** [scope guard — e.g. no redesign, no new deps]
**Files / areas (estimate):** ~N files — [list groups, not every path unless seasoned asks]
**Risks:** [max 3, one line each]
**Verify after:** [click path, command, or test name]
**Persona note:**
- viber: [one term they'll see, e.g. "refactor = rearrange without changing behavior"]
- seasoned: [main decision, e.g. "extract service layer vs inline handlers"]
**Lifecycle note:** [if change touches auth/secrets/CI — flag pre-ship/security/devops later]
Proceed? (yes / adjust / just ship)
See reference.md for examples by change type.
Phase 3: Wait or execute
| User reply | Action |
|---|
| yes / go / lgtm | Execute plan; meta skill emits lesson after |
| adjust | Revise plan once; ask what to narrow |
| just ship | Execute without re-planning |
| silent + already said "plan and go" | Execute |
STOP: Do not edit files until confirmation unless user explicitly combined plan+execute in one message.
Phase 4: After execution
Suggest:
/devlearn-explain-diff if many files changed/devlearn-pre-ship when user says release-ready/devlearn-security if auth/secrets touched
Persona integration
| Persona | Plan emphasis |
|---|
| viber | Plain English steps; one term; verify = "click X and see Y" |
| seasoned | Risks, rollback, decision preview; optional file list |
| autodetect | Match user message formality |
Common mistakes
| Smell | Fix |
|---|
| Plan is pseudo-code | Plain English only |
| 40-file plan with no grouping | Cluster into 3–6 intent groups |
| Confused with pre-ship | Link lifecycle doc |
| Plan for one-line fix | Skip skill |
Red flags
| Situation | Action |
|---|
| Deletes data / migration | Explicit backup + verify in plan |
| Production hotfix | Short plan still; note post-ship verify |
| User impatient | "just ship" overrides |
Required footer
---
DevLearn status: DONE | NEEDS_CONTEXT | AWAITING_CONFIRM
Plan files estimate: N
Suggested next: execute plan | /devlearn-explain-diff after | /devlearn-pre-ship when release-ready
---
Additional resources
- Examples by change type → reference.md
- Release checklist →
devlearn-pre-ship
- Ambient trigger →
devlearn-teach-while-coding
