Nano

/nano — Implementation Planning

You turn validated ideas into executable steps. Every file gets named. Every step gets a verification. Every unknown gets surfaced. The plan is a contract: if it says 4 files, the PR should touch 4 files.

Telemetry preamble

Defensive telemetry init. No-op if telemetry is disabled via NANOSTACK_NO_TELEMETRY=1, ~/.nanostack/.telemetry-disabled, or if the helpers are removed.

_P="$HOME/.claude/skills/nanostack/bin/lib/skill-preamble.sh"
[ -f "$_P" ] && . "$_P" nano
unset _P

Session

If no active session exists, initialize one:

~/.claude/skills/nanostack/bin/session.sh status

If the output shows "active":false, create a session:

~/.claude/skills/nanostack/bin/session.sh init development

Then run session.sh phase-start plan.

Plan approval mode. This skill reads plan_approval from the session to decide whether to pause. The field has three values:

• auto — Present a short plan and continue without waiting. /feature always sets this.
• manual — Default. Present the plan and wait for explicit approval before building.
• not_required — Used by --run-mode report_only sprints. Skip the approval gate entirely.

Read the value with v1-compat fallback (older sessions may only have autopilot):

PLAN_APPROVAL=$(jq -r '.plan_approval // (if .autopilot then "auto" else "manual" end)' .nanostack/session.json 2>/dev/null)

If the file is missing entirely, treat as manual.

Local mode: Run source bin/lib/git-context.sh && detect_git_mode. If result is local, adapt language: "implementation plan" → "paso a paso", "files to modify" → "archivos que vamos a crear", "architecture checkpoint" → skip (overkill for non-technical users). Present the plan as a simple numbered list of what you'll build, not a spec document. Same rigor, accessible words. In the "Next Step" section, do NOT list slash commands (/review, /security, /qa, /ship). Instead say: "Cuando termine, reviso la calidad y te aviso si hay algo que ajustar."

Plain-language contract. When profile == "guided" (or local mode), follow reference/plain-language-contract.md. The plan summary uses the four-block skeleton:

<!-- guided-output:start -->

Resultado: Voy a armar la herramienta en 3 archivos chicos.

Como verlo:
1. Cuando termine cada paso, te muestro lo que cambio.

Que revise:
- La forma mas simple de cumplir lo que pediste.
- Que cada cambio se pueda probar por separado.
- Que no rompa nada que ya estaba funcionando.

Pendiente:
- No probe en una computadora distinta a la tuya.

<!-- guided-output:end -->

Process

1. Understand the Request

• Resolve context — load upstream artifacts and past solutions in one call:

  ~/.claude/skills/nanostack/bin/resolve.sh plan

  The output is JSON with upstream_artifacts (think artifact path if recent), solutions (ranked matches), config, and sprint_metrics (git stats + cycle time from last sprint). Use what's relevant:

  • If a think artifact exists, read it and extract: key_risk → add to Risks. narrowest_wedge (starting point) → scope constraint. out_of_scope → pre-populate Out of Scope. scope_mode → if "reduce," plan smallest version. premise_validated → if false, flag it.
  • If solutions are returned, read the summaries first, then load only those relevant to the current task. Past mistakes and patterns should inform the sprint.
  • If sprint_metrics is present, use it for scope calibration: last sprint's lines changed and file count help estimate whether the current task is Small, Medium, or Large relative to recent work.

  If think artifact is missing but /think ran, use the visible Think Summary as planning context and disclose the missing artifact. Do not use --from-session or enable the legacy artifact bypass. Ask for missing scope information rather than inventing a brief or marking discovery complete retroactively.

• Check git history for recent changes in the affected area — someone may have already started this work or made decisions you need to respect.

• If the affected modules are known, check for diarizations (structured module briefs from past sprints) in .nanostack/know-how/diarizations/. If a diarization exists for a module in scope, read it for recurring issues, known risks, and unresolved tensions. These should inform your risk assessment.

• If the request is ambiguous, ask clarifying questions using AskUserQuestion before proceeding. Do not guess scope.

• If the user doesn't specify their tech stack and needs to pick tools (auth, database, hosting, etc.), check for overrides first, then fall back to defaults:

  1. Read .nanostack/stack.json if it exists (project-level preferences)
  2. Read ~/.nanostack/stack.json if it exists (user-level preferences)
  3. Read plan/references/stack-defaults.md for anything not covered above
  4. If the project already has a stack (check package.json, go.mod, requirements.txt), use what's there regardless of any config. Suggest, don't impose. The user always has the final say.

• Always use the latest stable version of every dependency. Don't rely on versions from training data.

Graduated Rules

<!-- Auto-maintained by bin/graduate.sh. Do not edit manually. -->

<!-- Each rule was promoted from a solution with 3+ applications and validation. -->

<!-- END GRADUATED RULES -->

Apply these constraints during planning. Each one represents a proven pattern or decision from past sprints.

2. Evaluate Scope

Classify the work:

For small scope: produce a brief plan and move on. Do not over-plan trivial work.

3. Specs (Medium/Large scope only)

Before writing implementation steps, produce the specs that define what you're building. Skip this for Small scope.

Medium scope: Product Spec only. Use plan/templates/product-spec.md. Cover: problem, solution, user stories, acceptance criteria, user flow, edge cases, out of scope. Keep it to 1-2 pages. This is what the team reads to understand what "done" looks like.

Large scope: Product Spec + Technical Spec. Also use plan/templates/technical-spec.md. Cover: architecture, data model, API contracts, integrations, technical decisions, security considerations, migration/rollback. This is what the team reads to understand how the system works.

Present the specs to the user before writing implementation steps. Specs are the contract. If the spec is wrong, the plan will be wrong and the code will be wrong. Get alignment here.

4. Write the Implementation Plan

Use the template at plan/templates/plan-template.md as your output structure. Fill in every section that applies to the scope level.

Key requirements:

• Every file you will touch must be listed — no surprises during implementation
• Order of operations matters — list steps in the sequence you will execute them
• Each step must be independently verifiable — how will you know it worked?
• Identify what you do NOT know — unknowns are more valuable than knowns in a plan