Preplan

/preplan $ARGUMENTS

You are creating a pre-plan draft — the stage that comes before /plan-task and /plan-epic.

A pre-plan is not an implementation plan. It is the clay model: the final shape is unknown until the pre-plan is finished. It exists so the user can think in shapes — how many stages, which data, which code, how hard the deploy — without committing to any of them. It is high-level by design and it changes over time.

Your job is to produce the boilerplate, with a guideline under each section telling the user what remains to be filled in. You do not design the solution.

The skill runs in one of two modes, chosen by a flag on the command line:

• Prefill (default) — each section carries the analysis the Jira ticket genuinely supports, plus its guideline.
• Scaffold (--no-prefill) — the header block is still filled from the ticket, and sections 1 through 6 carry only their guideline. Use this when the ticket would mislead more than it helps, or when the shape is already in the user's head and ticket-derived prose would just have to be deleted.

Step 0 — Parse arguments

$ARGUMENTS contains the raw input. Split it into:

• TASK_ID: the first whitespace-separated token (e.g., MLID-2822).
• PREFILL: false when the token immediately after TASK_ID is --no-prefill, --blank or --raw; true otherwise. Consume the flag token when present — it is never part of EXTRA_CONTEXT.
• EXTRA_CONTEXT: everything remaining, with surrounding quotes ("..." or '...') stripped. May be empty.

Treat EXTRA_CONTEXT as user guidance about what the pre-plan should emphasise — not as part of the ticket. It can narrow scope, point at a layer that matters most, or flag a constraint. If it is empty, proceed normally.

Never ask the user which mode to use. The flag is the whole answer: absent means prefill, present means scaffold. If the user writes something flag-like that you do not recognise, treat it as EXTRA_CONTEXT and say so when you report.

The output file is always docs/agomez/preplans/{TASK_ID}.md — bare ticket ID, no slug. The mode does not change the filename.

Step 1 — Check whether the file already exists

Before doing anything else, check for docs/agomez/preplans/{TASK_ID}.md.

If it exists, STOP and ask the user which they want:

1. Overwrite the existing file
2. Write to docs/agomez/preplans/{TASK_ID}-v2.md instead
3. Abort

Never overwrite without an explicit answer. A pre-plan is shaped over days; a re-run must not be able to erase that work.

Step 2 — Read the Jira ticket

Use the Atlassian MCP to read issue TASK_ID. Cloud ID: 958cb046-2571-47a5-a29b-8baa0bee65b2.

Extract:

• Summary and description
• Acceptance criteria, if present
• Issue type (bug, story, task) and story points, if set
• Parent or epic link, if it is a sub-task
• Comments, when they carry scope or constraint information

Read the ticket in both modes. When PREFILL is false you still need the title, issue type and parent epic for the header block — that part is mechanical transcription, not analysis, so it is always filled. What the flag turns off is the reasoning in sections 1 through 6.

Do NOT investigate the codebase. No codebase-investigator, no Explore agent, no reading source files. This skill works from the ticket alone. Naming a file or component is fine only when the ticket itself names it — otherwise the guideline asks the user to name it.

If the ticket is thin or missing detail, that is normal and expected. Say so in the affected section's guideline rather than inventing content.

Step 3 — Write the pre-plan boilerplate

Write docs/agomez/preplans/{TASK_ID}.md using the template below.

The header block — title, Jira link, issue type, parent epic, status, and the requested-focus line when EXTRA_CONTEXT is given — is filled from the ticket in both modes. Sections 1 through 6 depend on PREFILL.

When PREFILL is true (default), every section has two parts:

1. Analysis — what the Jira ticket genuinely supports, in plain prose or a short table.
2. A guideline — an italic _To complement:_ line naming what is still open in that section, so the user knows exactly what to add.

The _To complement:_ line is the boundary between your inference and the user's work. It stays until the user deletes it.

When PREFILL is false, sections 1 through 6 hold their guideline line and nothing else.

• Drop every <...> placeholder body. Do not write prose, do not write a holding sentence such as The ticket does not indicate any data change.
• Drop the tables in sections 2, 3 and 4 as well — keep only their header row and one empty row, so the shape stays visible without implying content.
• Rewrite each _To complement:_ line as a plain _To fill:_ line describing what belongs in that section generically, since you have done no analysis to say what is missing from it. For example, section 3 becomes _To fill: which collections and tables are created, edited, read or deleted, and why. Names only._
• Add > Scaffold only — sections below were not prefilled from Jira. immediately under the status line, so a reader months later knows the emptiness was chosen, not an oversight.

This mode matches the layout of /postmortem: real content in the title and header, guidelines everywhere else, filled in by the user afterwards.

Template

# [{TASK_ID}] <type>(<scope>): <short description>

Pre-plan / effort analysis. Not an approved implementation plan yet.

- **Jira**: [{TASK_ID}](https://localinfusion.atlassian.net/browse/{TASK_ID})
- **Issue type**: <bug | story | task>
- **Parent epic**: <epic id, or "none — standalone">
- **Status**: Draft

<!-- Include this line ONLY when PREFILL is false -->
> Scaffold only — sections below were not prefilled from Jira.

<!-- Include this block ONLY when EXTRA_CONTEXT is non-empty -->
**Requested focus:** <EXTRA_CONTEXT verbatim>

---

## 1. Summary

<What the ticket asks for, in three to six sentences, in the user's own problem terms.
Say what is broken or missing and what "done" looks like. No solution design.>

_To complement:_ <what the ticket does not make clear about the problem itself —
missing acceptance criteria, undefined scope boundaries, unstated users or environments.>

## 2. High-level steps

<How many stages the eventual plan will likely contain, and what each covers.
One line per stage. Stages, not tasks — this is the shape of the work, not its schedule.>

| # | Stage | What it covers |
|---|-------|----------------|
| 1 | <name> | <one line> |
| 2 | <name> | <one line> |

_To complement:_ <whether the stage count is right, which stages can ship independently,
which ones must land together and why, and which stage carries the risk. Dependencies
between stages, not a schedule and not a commit breakdown.>

## 3. Data overview

<Which collections, tables or documents are created, edited, read or deleted.
Names only. No schemas, no field lists, no query bodies.>

| Collection / table | Action | Why |
|---|---|---|
| <name> | create / edit / read / delete | <one line> |

_To complement:_ <collections the ticket does not mention, whether any change is
destructive or reversible, and whether Mongo and Postgres are both in scope.>

## 4. Code overview

<Which components, services, jobs, API routes or packages are created, modified,
reorganised or deleted. Names and paths only. No code, no signatures.>

| Area | Action | Why |
|---|---|---|
| <component / service / route> | create / modify / reorganise / delete | <one line> |

_To complement:_ <surfaces the ticket does not name, whether anything in @repo/ui
already covers the UI need, and which existing behaviour must not regress.>

## 5. Deploy overview

<Anything beyond a normal code deploy: database migrations, terraform or
infrastructure changes, new environment variables, new secrets in Azure Key Vault,
feature flags, job or worker changes, backfills, ordering constraints between steps.

Describe migrations by what they do — never by number. See the boundary on
migration numbers below.

If the deploy is plain — code only, no migration, no infrastructure — write exactly:
"Plain deploy. No migration, infrastructure change, environment variable or feature flag expected."
and leave it at that.>

_To complement:_ <whether a feature flag should gate this, whether a backfill is
needed for existing records, and whether anything must be deployed in a set order.>

## 6. Open questions

<Decisions that are not yet made. One numbered entry each, phrased as a question with
the options visible where they are known. This is where the clay is still soft —
prefer parking a decision here over resolving it silently.>

Numbers are stable: assigned in document order, never reused and never renumbered.
When a question is answered, record the answer under its own number rather than
deleting the entry, so a reference to "Q3" means the same thing months later.

- **Q1 — <question?>** — options: <a> / <b>
- **Q2 — <question?>**

_To complement:_ <add every decision you do not want the implementation plan to
assume on your behalf.>

Filling rules

• Prefill mode only: replace <...> placeholders with real content. Never ship an angle-bracket placeholder in a section you could fill from the ticket.
• Prefill mode only: where the ticket gives you nothing for a section, write one honest line — for example The ticket does not indicate any data change. — and let the _To complement:_ line carry the rest. Do not leave a section body empty and do not pad it.
• Keep the tables in both modes. An empty row is better than a removed table, because the shape itself is the message.
• The header block is filled from the ticket in both modes. Status is always Draft, never Scaffold — the scaffold marker is its own line.
• The title uses the project commit convention: [MLID-XXXX] <type>(<scope>): <short description>.
• Dates, if any appear, use MM/DD/YYYY.
• Open questions are always numbered, in both modes — Q1, Q2, Q3, assigned in document order. Keep the stability note above the list. In scaffold mode the section keeps the note and the two numbered placeholder entries, the same way the tables keep their header row. Number them as you add them while shaping the document, and never renumber the survivors when one is answered.

Step 4 — Report and stop

Print the path of the file you wrote, and which mode you used — prefilled from Jira or scaffold only — and stop. Do not echo the document into the conversation, do not start planning, do not touch source code.

Naming the mode matters: it is the user's only confirmation that the flag parsed the way they intended. If you fell back on an unrecognised flag-like token and treated it as EXTRA_CONTEXT, say that here too.

Tell the user the draft is ready to shape, and that /plan-task {TASK_ID} is the next stage once the clay has set.

Boundaries

These are hard rules. They define what a pre-plan is.

• Strictly high-level. Table names, collection names, component names, file names, route names. Never code lines, never full table or schema definitions, never function signatures, never query bodies.
• Written for a mixed audience. Software engineers, data architects, principal engineers, software architects and product owners must all be able to read it. Prefer plain language over jargon. Spell identifiers out; avoid abbreviations. Avoid idioms — the reader may not be a native English speaker.
• Focus on the three overviews. Plan steps, data overview and code overview carry the weight. Do not drift into implementation detail anywhere.
• Follow the project architecture rules in CLAUDE.md. Monorepo layout, @repo/ui first for user interface work, Mongoose for data access, service layer over direct database calls, feature flags from the MongoDB-backed service, role-based access control enforced at both the interface and the API. When the ticket implies something that conflicts with those rules, raise it as an open question in section 6 rather than resolving it.
• Branching strategy yes, commit strategy no. Record where the work lands — the base branch, whether the ticket is an epic sub-task or standalone, and whether its type implies a particular pull-request shape (a hotfix ships two pull requests from one branch). That is structural, it is read by everyone, and getting it wrong is expensive. Never record how the work is carved up — commit breakdown, how many commits a stage should be, branch names to create, pull-request sequencing. Those depend on what the code actually looks like, and this skill investigates no code, so anything written about them is a guess a later session will treat as a given. /plan-task and /implement-task own them. If a section starts asking whether something should be "one commit or several", delete the question rather than answering it.
• Never write a migration number. Not the next number, not the current last entry, not "as a sanity check". Many engineers push to develop daily, so both migration sequences — Drizzle in packages/db/migrations and Mongo db-update — move constantly, and any number written into a document is wrong within days. Someone reading it later takes it as an input rather than the stale guess it is. Refer to a migration by what it does ("one additive migration adding the six columns"), and where the number matters, state the rule instead of a figure: read it from the migration journal at the moment the migration is generated, and read it again immediately before the branch merges. This applies to every document this skill writes, and to anything you say when reporting.
• Never decide alone. Any judgement call — scope, approach, trade-off, which of two designs — goes into section 6 as an open question. The pre-plan records decisions the user makes; it does not make them.
• No codebase investigation. The ticket is the only input, plus EXTRA_CONTEXT when given.
• The mode is chosen by the flag, never by you and never by a question. Prefill is the default. --no-prefill suppresses the analysis in sections 1 through 6; it never suppresses the header block, and it never changes the filename or the section list.
• No implementation code, ever.