Break Down Functional Spec
Always use the skill
to retrieve the ***plain syntax rules — but only if you haven't done so yet.
When to Use
analyze-if-func-spec-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
file it belongs to.
Workflow
- Read the full file — definitions, implementation reqs, and all functional specs (including modules) to understand context.
- Identify the spec to break down — the one flagged as too complex or pointed to by the user.
- 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?
- 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
- 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.
- 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.
- Verify each replacement spec — run
analyze-if-func-spec-too-complex
- Check for conflicts — run once with the full set of replacement specs plus every existing spec in the file and its 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 , then re-run over the touched set until the verdict is .
- Replace in the file — remove the original spec and insert the replacement specs in its position, preserving chronological order.
- 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:
plain
- :User: should be able to create, edit, and delete :Recipe: items, with
validation on all fields.
After:
plain
- :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:
plain
- 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:
plain
- 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:
plain
- The system should fetch :Ingredient: data from the external API with
pagination, retry on transient errors, and cache results for 10 minutes.
After:
plain
- 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:
plain
- 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:
plain
- 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:
plain
- 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:
plain
- 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