planning

name	planning
description	Plan work using Mighty (mt) by creating/updating specs and structuring implementation tasks. Use when asked to plan or break down a change, draft a spec (feature/rule/invariant/bug), or turn a fuzzy request into a structured Mighty spec tree with linked tasks.

Planning

Overview

Create or update Mighty specs that explain what should change and why, then create linked Mighty tasks whose bodies are reviewable and implementation-shaped without reopening the full spec tree.

Progressive disclosure rules

• Assume mt prime has already been run for this session; only run it if you’re missing mt conventions/context.
• When describing workstream restore, publish, or recovery behavior, model workstream_ref as the mutable latest-state scope and checkpoint IDs as the rewrite-stable lineage anchors beneath it.
• Prefer the smallest artifact that preserves intent:
  • Update an existing spec/task/decision if it already captures the intent.
  • Create a new spec only when there isn’t a suitable one.
• Create or update a decision only when you’re choosing between alternatives or setting a lasting constraint. If the task is specifically about decision authoring, use the sibling decisions/ skill.
• Keep descriptions structured and high-signal. Prefer precise wording over terse wording, and use nested lists when they make one guarantee or constraint easier to understand.
• When you create execution tasks, assume a human reviewer or worker may read the task before opening every cited spec/decision. Copy the decisive contract facts and the rough implementation shape into the task body; citations support the task, but must not be the only place the real requirements live.

1) Pull current context (docs + graph + code)

• If there’s a docs/ tree, run tree docs | head -n 200 and skim the relevant indices before proposing changes.
• Search the Mighty graph before grepping code:
  • mt search <keyword>
  • mt tree / mt tree <spec-id>
  • mt show <id>
• Then inspect code paths with rg and open only the files needed to avoid guessing.

2) Create or update the spec(s)

Before writing, decide whether you're writing a product spec or a technical spec — they use different templates. See references/spec-template.md for both templates and writing guides. For examples, open references/examples.md to find the right domain file, then open only that file.

Product specs vs technical specs

Product specs and technical specs are different documents serving different purposes.

Product specs describe a product area — what problem it solves, what the goal is, how the approach works, and what success looks like. They answer the questions a new team member or stakeholder would ask about a capability.

• Use the Problem/Goal/Approach/Success template (see references/spec-template.md).
• Guarantees-style bullets are not used. Instead, the Approach section names the key concepts and how they relate.
• implemented_by edges point to technical specs, never directly to code.
• No ## States, ## Verifications, wire protocols, data schemas, or implementation mechanisms. If you're describing how the system fulfills a promise rather than what it promises and why, you're writing a technical spec.
• Readability test: a new team member understands the product area in under 3 minutes.

Technical specs define implementation contracts — the guarantees and constraints that drive code. This is the existing Guarantees + Constraints format.

• implemented_by edges point to code files and commits. This is the terminal layer.
• May include ## States, ## Verifications, and implementation-specific detail.
• A technical spec may be a child of a product spec or a child of another technical spec.

The linking chain: Product spec → (implemented_by) → Technical specs → (implemented_by) → Code files.

When to write which:

• Defining a new product area or capability cluster → product spec
• Breaking a product spec into buildable units → technical specs, linked via implemented_by
• Decomposing a technical mechanism further → child technical spec via child_of
• Cross-cutting mechanism used by multiple areas → technical spec linked from multiple product specs via implemented_by

Linking product to technical:

• Use implemented_by (not child_of) to connect product specs to technical specs: mt link --from <product-spec> --rel implemented_by --to-spec <technical-spec> -d "Implements <product goal> via <technical approach>"
• Cross-cutting technical specs can be referenced by multiple product specs — this is the intended way to handle concerns that span product areas without needing multiple parents in the tree.
• Reserve child_of for decomposition within the same kind: product-to-product (breaking a large product area into sub-areas) or technical-to-technical (refining a parent guarantee into a specific sub-contract).

Technical spec authoring (Guarantees + Constraints)

• Structure technical specs with Guarantees (everything the system promises) and Constraints (everything the system prevents).
• Add ## Verifications when concrete examples, edge cases, or noop/scope rules should be spelled out as test-shaped checks. This section is optional, but when present it should read like a guide for the tests that ought to exist.
• Add ## Open Questions when a spec has unresolved items. Mark each as [blocking] (spec is not implementation-ready) or [non-blocking]. When resolved: update Guarantees/Constraints if the answer changes contract, record a Decision if it was a significant tradeoff, or leave implicit if it's discretion.
• What belongs where (contract / decision / discretion split):
  • Guarantees: observable behavior any valid implementation must satisfy (the contract).
  • Decisions: durable tradeoffs that future work must respect — record via mt decision new and link to the spec rather than embedding in Guarantees.
  • Discretion: everything else. The implementing agent may choose without recording a decision. Add a ## Discretion section only when the boundary is ambiguous — choices someone might mistake for a missing guarantee.
  • Use the significance threshold to decide whether a choice is a Decision or discretion: user-visible behavior, security/privacy, money/billing, compatibility/migration, data shape/API contract, cross-spec invariants, objective tradeoffs.
• Use citation links when referencing other entities: [Title](cite:<id_prefix>-spec-...) (always include link text).
• Parent specs should act as umbrella contracts. Child specs should refine one guarantee, one constraint, or one tightly related cluster of promises from the parent.
• Use nested lists when a guarantee or constraint has meaningful sub-points, modes, or scoped refinements. The top-level bullet should still read as a complete claim on its own.
• Readability test: the parent summary, child titles, child_of descriptions, and evidence descriptions together should explain the intent, the implemented coverage, and the gaps without needing to inspect code first.
• For a large effort, create a parent spec and then add child specs that make the refinement explicit.

Tree structure: Product and Technical roots

The spec tree has two roots: Product and Technical. Use mt tree to find them.

Product contains product specs organized by product area. New product specs go under Product. A product spec can have child product specs (sub-areas) but should not have technical spec children — use implemented_by to link to technical specs instead.

Technical contains technical specs organized by intent area. New technical specs go under the appropriate intent area. If no area fits, create it as a direct child of Technical — but check existing areas first with mt tree.

Placement rules:

• One-time changes (migrations, renames, backfills) are tasks, not specs
• Shipped bug fixes are tasks, not specs
• Completed evaluations ("should we use X?") are decisions, not specs
• CLI commands go under the CLI technical area, not under the product area they serve
• Build conventions and test infrastructure go under their system area, not as standalone roots
• When creating a new spec, check mt tree for the right parent before defaulting to a root

Spec hygiene: when to split, merge, or move

One spec = one composable concept. A spec should describe a concept that is distinct, independently useful, and not just a different angle on something another spec already covers. Before creating a new spec, ask: "Does this describe something a developer could implement or reason about independently, or is it an aspect of an existing spec?"

The same-file test. If two specs are both implemented_by the same source file, they are probably the same concept described from two angles. Merge them. A 200-line file does not need two specs.

Don't split iteratively. When a design question arises during implementation (e.g., "how should retry logic work for notifications?"), the answer belongs in the existing spec as a new guarantee or constraint — not as a new child spec. Create a child spec only when the concept genuinely decomposes (e.g., "deploy target configuration" is a distinct concept from "rollback logic," even though they interact). Two concrete triggers for when splitting is right: (1) the sub-mechanism has grown enough guarantees that the parent spec is hard to read as one concept, or (2) the sub-mechanism is reused by other specs and needs its own identity.

Parent specs must have a thesis. A parent spec that is just an index of its children — listing them without adding its own guarantees, constraints, or framing — is not doing useful work. Either give it real content (product spec: Problem/Goal/Approach/Success; technical spec: umbrella guarantees) or eliminate it and let the children be roots or move under a parent that has a thesis.

Place specs where they belong. CLI commands belong under the CLI tree. Test artifacts don't belong in the spec tree at all. Completed evaluations ("should we use Temporal?") are decisions, not specs. If a spec keeps getting miscategorized, the tree structure has a gap.

Draft vs Active. Specs for unbuilt features should be Draft. Don't mark a spec Active until working code implements its guarantees. If a spec has been Draft for months with no implementation path, consider whether it's a spec or a wish.

3) Record decisions (ADR-style)

Use mt decision new when you choose between alternatives or set constraints the code must follow.

Template: references/decision-template.md

• For example decision text, open references/examples/decision.md.

4) Pressure-test leaf technical specs before task creation

Before spawning tasks, review each implementation-bound leaf technical spec through these lenses (ordered by discovery value). Product specs are evaluated by Problem/Goal/Success clarity, not by these lenses.

1. Failure / recovery: For each guarantee, what happens when it can't be fulfilled?
2. External boundaries: Where does this spec interact with systems or specs outside its control?
3. State / data invariants: What must always be true? Race conditions? Partial-update scenarios?
4. Objectives / budgets: Are there latency, size, cost, or resource constraints?
5. Inputs / events: Edge-case inputs? (empty, maximum, malformed, concurrent)
6. Verification: How would you prove each guarantee holds? Is that automatable?
7. Actor / outcome: Are actor expectations unambiguous?
8. Explicit freedoms: Are there decisions that look like freedom but actually matter?

Rules:

• At most one question per lens. Hard cap of 8 questions per spec.
• Hit lenses 1–4 first. If all come back clean, lenses 5–8 are optional.
• Strict mode (blocks task creation): implementation-bound leaf specs and external-interface specs.
• Advisory mode (report only): exploratory work, refactors, parent/framing specs.
• If a gap changes user-visible behavior or non-negotiables → update the spec before creating tasks.
• If a gap only affects internal shape → mark as discretion and move on.
• This is a necessary-conditions check, not a completeness proof.

5) Spawn execution tasks from the spec(s)

• Create implementation tasks with mt task new --source <spec-or-decision-id> so the graph tracks provenance.
• Every implementation task should stand on its own for review and handoff. If someone read only the task body, they should still understand the required change, the main invariants, the important non-goals, and roughly what the code will do.
• Make the task body read like light pseudocode when the work is non-trivial:
  • what starts the flow
  • the important branches or state transitions
  • the main side effects or persisted outcomes
  • what must never happen
• Leave room for implementation judgment on naming, helper factoring, and local plumbing unless those choices are themselves part of the contract.
• Acceptance criteria should still be observable contract checks, but the task body should supply enough implementation detail that a reviewer can predict the downstream code shape without guessing.
• If the draft task would force a reviewer to infer the real requirement from phrases like “support guest bootstrap” or “wire this up,” rewrite it into stepwise, implementation-shaped language first.

Template: references/task-template.md

• For example task text, open references/examples/task.md.

6) Link structure and evidence

• Use semantic child_of descriptions when organizing a tree deliberately:
  • mt link --from <child-spec> --rel child_of --to-spec <parent-spec> -d "Refines <parent guarantee or constraint> into <specific sub-contract>"
• Evidence descriptions should read like small semantic coverage claims so later review can map spec guarantees and constraints to implementation/test/reference artifacts.
• Link evidence from the most specific live spec or task that owns the guarantee or constraint. Keep umbrella parents focused on cross-cutting or umbrella evidence.
• When a parent accumulates implementation/test links that obviously belong to distinct children, split the intent into child specs and move the evidence down.
• For screenshots or external files referenced in spec/task text:
  • Upload: mt file upload <path>
  • Embed in rich text with returned file_id: ![[file <file_id>]] (block) or [[file <file_id>]] (inline)
  • Optionally link artifact evidence: mt link --from <spec-or-task> --rel documented_by --to-type file --to-ref mighty-file:<file_id> -d "Screenshot/reference artifact showing <specific guarantee or constraint> for <specific flow or state>"

7) Reconcile after implementation

After a task is closed, run a reconciliation pass against the source spec:

• Compare the diff + test results against each guarantee/constraint.
• Produce a contract delta for each guarantee/constraint:
  • Matches spec: code satisfies this claim.
  • Spec silent: code introduces behavior the spec doesn't cover → surface as a decision candidate.
  • Violates spec: code contradicts a claim → fix code or propose a spec update.
  • New capability: code adds functionality beyond spec scope → propose child spec or spec update.
  • Spec was wrong: implementation reveals a guarantee is infeasible → propose spec update for review (not automatic — the implementing agent has a conflict of interest).
• Resolve all decision candidates before closing. Candidates are never auto-promoted.
• In-flight severity policy:
  • Stop and re-gate: external contract conflicts, security/privacy, money, compatibility, data-shape changes.
  • Continue with candidate + reconcile at closeout: local tradeoffs that don't change declared guarantees/constraints.
  • Continue with assumption note: small reversible ambiguities.

8) Sync planning artifacts

Run mt commit to commit .mighty changes.

Reference templates

• Spec structure: references/spec-template.md (product spec and technical spec templates)
• Decision structure: references/decision-template.md
• Task structure: references/task-template.md
• mt shell patterns: references/mt-command-patterns.md
• Examples index: references/examples.md (points to domain-specific files in references/examples/)