Analyze If Functional Spec Is Too Complex
Always use the skill
to retrieve the ***plain syntax rules — but only if you haven't done so yet.
Why This Matters
The renderer enforces a hard complexity limit: each functional spec must imply a maximum of 200 changed lines of code. If a spec exceeds this, the renderer rejects it with "Functional spec too complex!" and the spec must be broken down. Catching this before insertion saves a failed render cycle.
Input
A drafted functional spec (not yet inserted into the file), plus the full context of the
file it will be added to — definitions, implementation reqs, and existing functional specs.
Workflow
- Read the full file (and any / modules) to understand the current codebase context — what already exists and what the new spec builds on.
- Read the drafted functional spec carefully.
- Run the complexity analysis using the checklist below.
- Output the verdict and nothing else — either or . No reasoning, no LOC estimate, no breakdown.
Complexity Analysis Checklist
Work through each indicator. A single "yes" does not automatically mean the spec is too complex, but multiple "yes" answers are a strong signal.
1. Number of Distinct Behaviors
Does the spec describe more than one independently testable behavior?
Too complex:
- :User: should be able to create, edit, delete, and archive :Task: items,
with validation on all fields and confirmation dialogs for destructive actions.
Acceptable (one behavior each):
- :User: should be able to create :Task:. Only valid :Task: items can be added.
- :User: should be able to edit :Task:.
- :User: should be able to delete :Task:.
- :User: should be able to archive :Task:.
2. Number of Concepts Introduced or Modified
Does the spec require introducing new data structures, UI components, API endpoints, or other constructs that don't already exist? Count them.
- 0–1 new constructs → likely fine
- 2–3 new constructs → borderline, examine closely
- 4+ new constructs → almost certainly too complex
3. Branching Logic and Conditions
Does the spec describe multiple conditional paths, modes, or special cases?
Too complex:
- The system should process :Order: differently based on :OrderType:.
Standard orders are validated and stored. Express orders skip validation
and are queued for immediate dispatch. Bulk orders are split into
sub-orders of 100 items each, validated individually, and processed
in parallel with progress tracking.
Acceptable (separate the modes):
- The system should process standard :Order: by validating and storing it.
- The system should process express :Order: by queuing it for immediate dispatch
without validation.
- The system should process bulk :Order: by splitting it into sub-orders of 100
items each and processing them individually.
4. Cross-Cutting Concerns
Does the spec bundle core functionality with cross-cutting concerns like error handling, logging, retry logic, pagination, or caching?
Too complex:
- The system should fetch :Resource: items from the external API with
pagination support, retry on transient errors with exponential backoff,
cache results for 5 minutes, and log all API calls.
Acceptable (separate concerns):
- The system should fetch :Resource: items from the external API.
- The system should paginate when fetching :Resource: items from the external API.
- The system should retry fetching :Resource: on transient errors using
exponential backoff.
5. UI Complexity
Does the spec describe a complete screen or page with multiple interactive elements, layouts, and state transitions?
Too complex:
- Display a dashboard showing :User: profile, recent :Task: items in a
sortable table, a notification bell with unread count, and a sidebar
with navigation links that highlights the active page.
Acceptable (build incrementally):
- Display a dashboard page for :User:.
- Show recent :Task: items in a sortable table on the dashboard.
- Show a notification indicator with the unread count on the dashboard.
6. Data Transformation Complexity
Does the spec involve complex data mapping, aggregation, or transformation across multiple entities?
- Simple field mapping or filtering → likely fine
- Multi-step transformations, joins across entities, or aggregations → likely too complex
7. Rough LOC Estimation
Mentally estimate the implementation. Consider:
- New files that need to be created
- New functions/methods
- Data model changes (schema, migrations, types)
- UI components (if applicable)
- Test setup and assertions (unit tests are auto-generated alongside)
- Error handling paths
- Import statements and boilerplate
If the estimate exceeds ~150 LOC, the spec is at high risk of being too complex (leave headroom for the renderer to add necessary boilerplate).
Output Format
The skill emits exactly one of these two strings, with no surrounding text, explanation, estimate, or breakdown:
or
The internal analysis (checklist, LOC estimation, reasoning) informs the verdict but must not appear in the output. The caller decides what to do with the result.
Integration with add-functional-spec / add-functional-specs
This skill is called during step 3 of the
workflow (or per spec during
), after drafting a spec but
before inserting it into the file. The caller acts on the one-word verdict:
- ACCEPTABLE — proceed to insert the spec.
- TOO COMPLEX — invoke to produce smaller specs, then insert each one individually (running conflict checks on each).