Plan to spec

Plan to Spec

Turn the current conversation and codebase understanding into a spec, and stage it as a local file. Do not interview the user — synthesize what's already been discussed. To sharpen an idea before it's ready, run /grill-with-docs (or /work-plan for a large effort) first; this skill is the write-up step after the thinking is done.

Local-first. The spec is written to local storage by default. It is never pushed to Confluence (or any remote) without the user explicitly asking, and never without confirming the destination first. The local file is the source of truth; Confluence is an optional downstream copy.

Process

1. Resolve the staging location

The spec lands in a staging directory the user controls, laid out spec-kit style: one numbered feature folder per spec.

<staging>/NNN-<feature-slug>/spec.md

Resolve <staging> in this order:

1. A path the user passed as an argument this run.
2. The memory default reference_plan_staging_dir.md, if it exists.
3. Otherwise ask where to stage (offer a sensible default like ./specs/ or .plans/ under the repo). Offer to record the answer to reference_plan_staging_dir.md so future runs skip the prompt — record only if the user agrees.

Pick the next free NNN (zero-padded, starting 001) in the staging dir and a kebab-case <feature-slug> from the feature name. State the resolved path back before writing.

2. Explore the repo

If not already, explore to ground the spec in the current code. Use the project's domain vocabulary throughout (CONTEXT.md glossary if present) and respect ADRs in the area you're touching.

3. Sketch the test seams

Name the seams at which the feature will be tested. Prefer existing seams to new ones, and the highest seam possible — the fewer seams across the codebase, the better; one is ideal. Check the seams match the user's expectations before writing.

4. Write the spec locally

Write the template below to <staging>/NNN-<feature-slug>/spec.md. Report the file path. This is where the skill stops by default — the spec is staged, ready for /plan-to-tickets.

<spec-template>

<Feature name> — Spec

Problem Statement

The problem the user faces, from the user's perspective.

Solution

The solution, from the user's perspective.

User Stories

A LONG, numbered list, each As an <actor>, I want <feature>, so that <benefit>. Cover every aspect of the feature — be extensive.

Implementation Decisions

Modules built/modified, their changed interfaces, technical clarifications, architectural decisions, schema changes, API contracts, specific interactions. Do not include file paths or code snippets — they go stale. Exception: a prototype snippet that encodes a decision more precisely than prose (state machine, reducer, schema, type shape) — inline the decision-rich parts and note it came from a prototype.

Testing Decisions

What makes a good test here (external behaviour, not implementation details); which modules will be tested; prior art (similar tests already in the codebase).

Out of Scope

What this spec deliberately excludes.

Further Notes

Anything else.

</spec-template>

5. Publish to Confluence — only if asked

If — and only if — the user asks to publish, confirm the destination first (space + parent page, read the space key from reference_confluence_default_space.md), then create the page (confluence_create_page) from the staged spec.md. If the discussion traces to a Jira ticket, add a remote link from that ticket to the page (jira_add_remote_link). Record the published URL back into the local spec.md (a > Published: <url> line at the top) so the local copy points at its remote twin. Report the URL.

Rules

• Local-first, always. Write the local spec.md before anything else. It is the source of truth.
• No remote writes without an explicit ask AND a confirmed destination. Never publish to Confluence by default; never publish without confirming space/parent first.
• Staging location is the user's to choose. Argument > memory default > ask. Persist the default only with consent.
• Synthesize, don't interview. If you're asking design questions, the thinking isn't done — that's /grill-with-docs.

The staged spec feeds /plan-to-tickets, which breaks it into a local numbered task list.

Quality Loop

Before returning the artifact, evaluate it and refine if it falls short.

1. Generate the artifact via the workflow above.
2. Self-evaluate against these criteria:
   • Spec is staged as a numbered local spec.md (spec-kit style), not published unless asked
   • Every requirement traces back to a point settled in the source discussion
   • Open questions are listed rather than silently decided
   • No implementation detail leaks into what should be a requirements doc
3. Loop — if two or more criteria fail, revise and re-check.
4. Exit when all criteria pass, or after two refinement passes (then note which criteria still fall short).

Host portability: tool names follow Claude Code conventions; on other hosts map by intent — see PORTABILITY.md.

<!-- self-evolve:start -->

Self-Evolve Loop

This skill learns across invocations — the full contract is SELF-EVOLVE.md. Start: read the learnings journal — ~/.ink-and-agency/learnings/plan-to-spec.md and/or the workspace-local .ink-and-agency/learnings/plan-to-spec.md — if present, and apply its guidance. End: self-evaluate the results; optionally ask the user for feedback (never block on it); append signal-bearing learnings to the journal (user-global when the sandbox allows writing there, workspace-local otherwise); route skill-improvement ideas per the contract's tiers — edit the canonical source when one is present, never the plugin cache.

<!-- self-evolve:end -->