Functional Decomposition

Functional decomposition means breaking a feature into the smallest useful functions, user stories, and implementation steps before asking the agent to generate code. Instead of asking for "build the dashboard", you describe the behavior as a chain of focused issues.

Example:

ISSUE-1.md  Define dashboard data model
ISSUE-2.md  Load dashboard summary
ISSUE-3.md  Render dashboard cards
ISSUE-4.md  Add empty and error states
ISSUE-5.md  Add tests and Storybook examples

Each ISSUE-n.md file should describe one slice of behavior. A good issue contains the user story, the functional breakdown, the skills that apply, and the expected output.

Example:

# ISSUE-3.md

## User Story

As an account manager,
I want to see customer summary cards,
so that I can quickly decide which customer needs attention.

## Functions

- `getCustomerSummary(customerId)`
- `formatCustomerStatus(status)`
- `renderCustomerSummaryCard(summary)`

## Required Skills

- `.skills/SKILLS.md`
- `.skills/engineering-skills/react/molecule.md`
- `.skills/engineering-skills/quality/testing.md`
- `.skills/domains/customer-management.md`

## Expected Output

- React component
- Storybook story
- Vitest test

The user story explains why the work matters. The function list explains what must exist in the implementation. The skills explain how the agent must build it.

Example:

## User Story

As a user,
I want to filter products by availability,
so that I only see products I can order today.

## Functions

- `filterProductsByAvailability(products, availability)`
- `getAvailabilityLabel(availability)`
- `renderAvailabilityFilter(options)`

The function list does not need to be perfect upfront. Its job is to make the implementation smaller, reviewable, and testable. During implementation, the agent may discover better names or smaller functions, but it should keep the issue focused on the same behavior.

Example:

## Implementation Notes

- Keep filtering logic outside the React component.
- Keep labels in a small formatter function.
- Test filtering separately from rendering.

SKILLS.md should act as the default rulebook for every issue. It tells the agent which general architecture, testing, naming, and workflow rules must always apply.

Example:

# .skills/SKILLS.md

Always apply:

- engineering-skills/architecture/domain-modeling.md
- engineering-skills/react/component-patterns.md
- engineering-skills/quality/testing.md
- engineering-skills/workflows/generated-code-review.md

Topic-specific skills should be added to the issue when the work needs extra context. A customer management issue should reference customer skills. A payment issue should reference payment skills. A Storybook issue should reference Storybook skills.

Example:

## Required Skills

- `.skills/SKILLS.md`
- `.skills/domains/customer-management.md`
- `.skills/features/customer-overview.md`
- `.skills/engineering-skills/storybook/component-states.md`

This creates a clean contract for the agent: the issue says what to build, SKILLS.md says how the project builds software, and topic skills provide the domain-specific rules.

Example:

ISSUE-7.md
├── user story: what the user needs
├── functions: what the code should expose
├── required skills: which rules apply
└── expected output: what files should change

The best issues are small enough to implement in one branch and review in one pull request. If an issue contains too many user stories or too many unrelated functions, split it before starting.

Example:

Too large:
ISSUE-4.md  Build complete customer dashboard

Better:
ISSUE-4.md  Load customer dashboard summary
ISSUE-5.md  Render customer summary cards
ISSUE-6.md  Add customer dashboard empty states

Functional decomposition also improves skill extraction. After an issue is finished, you can inspect what worked and decide whether a rule belongs in a project skill, a topic skill, or the organization-wide SKILLS.md.

Example:

## Lessons Learned

- Customer status labels must come from the domain skill.
- Summary cards need loading, empty, error, and success stories.
- Filtering logic should be tested without React.

Mini Exercise

Choose one feature and split it into three ISSUE-n.md files. For each issue, write one user story, three function names, and the skills the agent should load.

Example

ISSUE-1.md  Define product overview model
ISSUE-2.md  Load product overview data
ISSUE-3.md  Render product overview page

Mini Exercise​

Example​

Mini Exercise

Example