break-down-func-spec

name	break-down-func-spec
description	Break down a functional spec that is too complex into smaller specs that each imply ≤ 200 lines of code. Use when analyze-if-func-spec-too-complex flags a spec as TOO COMPLEX, or when a spec is suspected of being too large.

Break Down Functional Spec

Always use the skill load-plain-reference to retrieve the ***plain syntax rules — but only if you haven't done so yet.

When to Use

• analyze-if-func-spec-too-complex flagged a spec as TOO COMPLEX.
• A spec is suspected of exceeding the 200 LOC limit and needs to be split preemptively.
• A spec bundles multiple behaviors, constructs, or concerns that should be separated.

Input

The functional spec to break down, plus the full .plain file it belongs to.

Workflow

1. Read the full .plain file — definitions, implementation reqs, and all functional specs (including requires modules) to understand context.
2. Identify the spec to break down — the one flagged as too complex or pointed to by the user.
3. Analyze why it is too complex — use the indicators from analyze-if-func-spec-too-complex:
   • Multiple distinct behaviors bundled together?
   • Too many new constructs introduced at once?
   • Complex branching logic or conditional paths?
   • Cross-cutting concerns mixed with core functionality?
   • A full UI screen described in one spec?
   • Complex data transformations across multiple entities?
4. Identify the split boundaries — find the natural seams where the spec can be divided. Each resulting spec must be:
   • Independently meaningful (makes sense on its own with previous specs as context)
   • Self-contained (does not require a later spec to be useful)
   • Within the 200 LOC limit
5. Draft the replacement specs — write the smaller specs in chronological order. The first replacement spec typically sets up the foundation, and subsequent ones layer behavior on top.
6. Verify functional completeness — this is critical. The replacement specs taken together must cover 100% of the functionality described in the original spec. Walk through every behavior, condition, and detail in the original and confirm it appears in exactly one of the replacement specs. Nothing may be lost, weakened, or left implicit. If any functionality from the original is missing, add it to the appropriate replacement spec or create an additional one.
7. Verify each replacement spec — run analyze-if-func-spec-too-complex on each to confirm it fits within the limit.
8. Check for conflicts — run analyze-func-specs once with the full set of replacement specs plus every existing spec in the file and its requires chain. The batched analyzer reports every conflicting pair (replacement × existing and replacement × replacement) in one call — do not loop over pairs. Resolve each reported pair with resolve-spec-conflict, then re-run analyze-func-specs over the touched set until the verdict is COMPATIBLE.
9. Replace in the file — remove the original spec and insert the replacement specs in its position, preserving chronological order.
10. Read the file again to confirm correct placement and syntax.

Splitting Strategies

Strategy 1: Separate Distinct Behaviors

If the spec bundles multiple independently testable actions, split each into its own spec.

Before:

- :User: should be able to create, edit, and delete :Recipe: items, with
  validation on all fields.

After:

- :User: should be able to create a :Recipe:. Only valid :Recipe: items can be created.
- :User: should be able to edit an existing :Recipe:. Validation rules apply to the edited fields.
- :User: should be able to delete a :Recipe:.

Strategy 2: Separate Setup from Behavior

If the spec introduces a new construct and immediately defines complex behavior on it, split into setup + behavior.

Before:

- The system should provide a :MealPlan: screen that displays a weekly grid of
  :Slot: items, allows drag-and-drop reordering, and shows nutritional totals
  per day.

After:

- The system should provide a :MealPlan: screen that displays a weekly grid of :Slot: items.
- :User: should be able to reorder :Slot: items within a day on the :MealPlan: screen using drag-and-drop.
- The :MealPlan: screen should display nutritional totals for each day.

Strategy 3: Separate Core Logic from Cross-Cutting Concerns

If the spec mixes primary functionality with error handling, retries, caching, pagination, or logging, pull cross-cutting concerns into their own specs.

Before:

- The system should fetch :Ingredient: data from the external API with
  pagination, retry on transient errors, and cache results for 10 minutes.

After:

- The system should fetch :Ingredient: data from the external API.
- The system should paginate when fetching :Ingredient: data from the external API.
- The system should retry fetching :Ingredient: data on transient errors.

Strategy 4: Separate Conditional Paths

If the spec describes different modes or branches, give each its own spec.

Before:

- The system should process :MealPlan: generation differently based on :DietType:.
  Standard plans use round-robin assignment. Restrictive plans filter out
  excluded ingredients first, then apply round-robin. Custom plans allow manual
  slot-by-slot selection.

After:

- The system should generate a standard :MealPlan: using round-robin :Recipe: assignment.
- The system should generate a restrictive :MealPlan: by filtering out excluded
  :Ingredient: items before applying round-robin assignment.
- The system should allow :User: to manually assign :Recipe: items to individual
  :Slot: items for a custom :MealPlan:.

Strategy 5: Build UI Incrementally

If the spec describes a full screen, split into layout + individual interactive elements.

Before:

- Display the :Dashboard: screen showing a summary card with stats, a scrollable
  list of recent :MealPlan: items, a floating action button to create a new plan,
  and a bottom navigation bar.

After:

- Display the :Dashboard: screen with a summary card showing :MealFrameStats:.
- The :Dashboard: screen should show a scrollable list of recent :MealPlan: items.
- The :Dashboard: screen should include a button to create a new :MealPlan:.

Preserving Chronological Order

The replacement specs take the position of the original spec. Earlier specs remain unchanged. The first replacement spec should make sense given only the specs above it. Each subsequent replacement spec can reference behavior from the ones before it.

If the original spec had acceptance tests, redistribute them to the most appropriate replacement spec — or drop tests that no longer apply to a single smaller spec and rewrite them.

Validation Checklist

• Original spec has been removed from the file
• Replacement specs together cover 100% of the original spec's functionality — nothing lost
• Each replacement spec implies ≤ 200 LOC (verified via analyze-if-func-spec-too-complex)
• No conflicts between replacement specs and existing specs (verified via one batched analyze-func-specs call)
• No conflicts between the replacement specs themselves (covered by the same batched call)
• Replacement specs are in correct chronological order
• Each replacement spec is independently meaningful
• All :Concepts: referenced in replacement specs are defined
• Replacement specs are language-agnostic
• All external interfaces remain explicit
• Acceptance tests (if any) have been redistributed or rewritten