mrdulasolutions/devlearn/devlearn-before-you-ship

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.

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

Meta skill (devlearn-teach-while-coding) should offer this automatically when thresholds hit.

Before you start

1. Estimate file count and blast radius (grep/read structure)
2. Read DEVLEARN.md persona — viber gets one term preview; seasoned gets decision framing
3. 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

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

Common mistakes

Red flags

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