input-hierarchization

name

input-hierarchization

description

Defines the canonical 8-layer system hierarchization tree (System → Functional Domain → Sub-Domain (optional) → Capability → Requirement → Business Process/Flow → Business Function → Use Case) and the per-layer authoring conventions (EARS, Mermaid TD, BPMN, Gherkin) used to classify and organize raw specification inputs. Use this skill whenever an input-analyzer agent must decide what a piece of input data IS, where it belongs in the system tree, or how to structure a heterogeneous input list — including specs, requirement documents, BPMN diagrams, OpenAPI files, user stories, or mixed legacy documentation.

Skill: Input Hierarchization

Purpose

Raw specification material arrives in heterogeneous shapes — a paragraph in a Word doc, a swagger endpoint, a BPMN lane, a user-story card, a diagram callout. Before any analysis can happen, each fragment must be answered against two questions:

1. What IS this fragment? (which layer of the tree does it belong to?)
2. Where does it ATTACH? (which parent node holds it?)

This skill provides the canonical hierarchization tree and the per-layer authoring conventions. Every analyst sub-agent (functional, technical, ui-ux, quality-compliance) must classify and place every retained fragment using the layers below; otherwise downstream skills (test-case-generator, coverage-checker) cannot align across lenses.

Companion skill — ears. Level-5 Requirement nodes must be authored in EARS syntax. Use the ears skill for the five patterns, cardinality rules, the mandatory Where → While → When|If → shall element order, and the review checklist that defines what needs-EARS-rewrite flags should detect.

---

The Tree

graph TD
    subgraph System ["System"]
        SOLUTION
    end

    System --> FD1[Functional Domain 1]
    System --> FD2[Functional Domain 2]
    System -.-> Elip1[...]

    FD1 --> SD1[Sub-Domain 1<br/><i>optional</i>]
    FD1 --> SD2[Sub-Domain 2<br/><i>optional</i>]
    FD2 --> Cap2[Capability 2<br/><i>direct child — no sub-domain</i>]

    SD1 --> Cap1[Capability 1]
    SD1 -.-> Elip5[...]

    Cap1 --> Req1[Requirement 1]
    Cap1 --> Req2[Requirement 2]
    Cap1 -.-> Elip2[...]

    Req1 --> BP1["Business Process / Flow 1:<br>'pack of ordered business functions'"]
    Req1 --> BP2[Business Process / Flow 2]
    Req1 -.-> Elip3[...]

    BP1 --> BF1[Business Function 1]
    BF1 --> BF2[Business Function 2]
    BF2 -.-> Elip4[...]

    BF1 -- "BPMN PATH 1" --> UC1[Use Case 1]
    BF1 -- "BPMN PATH 2" --> UC2[Use Case 2]

    Req1 --- N1[/"Expressed with EARS"\]
    BP1 --- N2[/"Expressed using Mermaid TD Chart"\]
    BF1 --- N3[/"Expressed in BPMN"\]
    UC1 --- N4[/"Expressed in GHERKIN"\]

    classDef solution_L1 fill:#3a4659,stroke:#6c7a89,color:#fff,stroke-width:2px;
    classDef domains_L2 fill:#2a6a4a,stroke:#3b8c63,color:#fff;
    classDef subdomains_L3 fill:#1f6f5c,stroke:#3b8c63,color:#fff,stroke-dasharray: 3 3;
    classDef capability_L4 fill:#a59345,stroke:#c9b35a,color:#fff;
    classDef requirements_L5 fill:#5e4a8c,stroke:#8c75bf,color:#fff;
    classDef bp_L6 fill:#9c3c3c,stroke:#cb5a5a,color:#fff;
    classDef bf_L7 fill:#b87333,stroke:#e69138,color:#fff;
    classDef uc_L8 fill:#2c7d7e,stroke:#3cb3a9,color:#fff;
    classDef grey fill:#333,stroke:#666,color:#fff;
    classDef representation_note fill:#c71585,stroke-dasharray: 5 5,color:#fff,stroke:#fff,stroke-width:1px;

    class System,SOLUTION solution_L1;
    class FD1,FD2 domains_L2;
    class SD1,SD2 subdomains_L3;
    class Cap1,Cap2 capability_L4;
    class Req1,Req2 requirements_L5;
    class BP1,BP2 bp_L6;
    class BF1,BF2 bf_L7;
    class UC1,UC2 uc_L8;
    class Elip1,Elip2,Elip3,Elip4,Elip5 grey;
    class N1,N2,N3,N4 representation_note;

The Sub-Domain layer (L3) is optional. When a Functional Domain is large enough to partition (multiple distinct teams, regulatory sub-areas, or product lines under one umbrella), introduce Sub-Domains and attach Capabilities to them. When the Domain is small or coherent, Capabilities attach directly to the Functional Domain and L3 is skipped — parent of an L4 Capability is then the L2 Functional Domain ID, not a Sub-Domain ID.

---

Layer Definitions

Level	Node	What lives here	Authoring convention
L1	System (Solution)	The top-level boundary — the product / solution under analysis. Exactly one root node.	—
L2	Functional Domain	A logical grouping of coherent business responsibilities — the department of the system. Stable, large-scoped, owned by a business stakeholder group.	—
L3	Sub-Domain (optional)	A partition inside a Functional Domain when the Domain is large enough to need internal grouping (multiple teams, regulatory sub-areas, product lines, lifecycle phases). Skip this level when the Domain is small or coherent.	—
L4	Capability	What the system is capable of doing to fulfill its mission. A stable power, expressed as a noun phrase. The what, not the how. Parent is the Sub-Domain (L3) when present; otherwise the Functional Domain (L2) directly.	—
L5	Requirement	A statement of what the system shall do or constrain, attached to a Capability.	EARS — When <trigger>, the <system> shall <response>, While <state>, …, If <condition>, …, ubiquitous, optional. See the companion ears skill. Non-EARS statements are flagged needs-EARS-rewrite.
L6	Business Process / Flow	A pack of ordered Business Functions that satisfies a Requirement. The temporal dimension.	Mermaid TD chart. Non-Mermaid flows are flagged needs-mermaid-normalization.
L7	Business Function	A user-invokable unit of behavior exercised inside a Business Process. Decomposes into branching paths.	BPMN 2.0 (lanes, gateways, events). Non-BPMN content is flagged needs-BPMN-normalization.
L8	Use Case	A concrete BPMN path through a Business Function — one user goal, one nominal flow + alternates, with acceptance criteria.	Gherkin — Given / When / Then scenarios with named scenario, tags, and example tables when relevant. Non-Gherkin assertions are flagged needs-gherkin-rewrite.

Edges

• A System has many Functional Domains.
• A Functional Domain has either Sub-Domains (when partitioned) or Capabilities directly (when not).
• A Sub-Domain (when present) has many Capabilities.
• A Capability has many Requirements.
• A Requirement is satisfied by one or more Business Processes / Flows.
• A Business Process orders one or more Business Functions.
• A Business Function branches into one or more BPMN paths; each path is one Use Case.
• A Use Case holds Gherkin scenarios (acceptance criteria).

Each node has exactly one parent on the spine; reuse across the tree is by reference, not duplication.

Sub-Domain decision rule: Introduce L3 only when at least one of the following is true:

• The Domain spans multiple ownership groups (different teams, squads, or business lines).
• The Domain mixes distinct regulatory or compliance regimes (e.g. retail vs. corporate, EU vs. US).
• The Domain has enough Capabilities that listing them flat under L2 obscures their grouping (rule of thumb: > ~6 Capabilities).
• The source material explicitly names a sub-grouping (e.g. "Sales — Physical Channels" vs. "Sales — Digital Channels").

Otherwise, attach Capabilities directly to the Functional Domain. Do not invent Sub-Domains for cosmetic structure.

---

Concept Dictionary (vocabulary)

The 8-layer tree above is the placement spine. The dictionary below gives each spine concept a verbatim definition.

#	Concept	Definition	Example	Spine layer
1	Functional Domain	A logical grouping of coherent business responsibilities — the department of the system. Stable, large-scoped, owned by a business stakeholder group.	Distribution and Sale	L2
2	Capability	What the system is capable of doing to fulfill its mission. A stable power, expressed as a noun phrase. Does not yet describe how it is used (the what). Attached to a Domain (or to a Sub-Domain when the Domain is partitioned).	Physical sales management	L4
3	Requirement	A statement of what the system shall do or constrain, attached to a Capability. Authored in EARS.	When the user submits …, the auth-service shall …	L5
4	Business Process / Flow	A pack of ordered Business Functions that satisfies a Requirement. The temporal dimension. Authored as a Mermaid TD chart.	The purchase of a ticket at the TVM	L6
5	Business Function	A user-invokable unit of behavior exercised inside a Business Process. Decomposes into branching paths. Authored in BPMN 2.0.	Contactless payment	L7
6	Use Case	A concrete BPMN path through a Business Function — one user goal, one nominal flow + alternates. Authored as Gherkin scenarios.	Pay with contactless card — happy path	L8

Legacy synonyms. Older specifications often use Feature (≈ L7 Business Function) and Process (≈ L6 Business Process / Flow). Preserve the source wording verbatim in each node's name; classify under the canonical layer.

Disambiguation rules

When a fragment looks like it could be two things, apply these tests in order:

• Capability vs. Business Function — is it a noun describing what the system can do (Capability — "physical sales management") or a noun describing the user-invokable service that exercises it (Business Function — "buy a ticket with contactless card")? Capabilities are reusable across many Business Functions.
• Business Function vs. Business Process — is the fragment a user-invokable unit of behavior with internal branching (Business Function — L7) or a cross-domain orchestration of multiple Business Functions (Business Process — L6)? A Business Function appears inside a Process step.
• Use Case vs. Business Function — a Use Case is a single BPMN path through a Business Function (one user goal, one Gherkin scenario). A Business Function holds the branching; the paths through it are Use Cases.

---

Classification Protocol (single fragment)

Given one piece of input, classify it in this order. Stop at the first match.

1. Is it the name of the product / solution itself? → System (L1).
2. Is it a top-level grouping / department name? → Functional Domain (L2).
3. Is it a partition inside a Functional Domain (named team area, regulatory carve-out, product line, lifecycle phase) AND the Sub-Domain decision rule is met? → Sub-Domain (L3). Otherwise treat the candidate as a Capability directly under L2.
4. Is it a noun describing a system power (the what)? → Capability (L4). Parent is the Sub-Domain (L3) when present; otherwise the Functional Domain (L2).
5. Is it a "shall" / "when … shall …" statement? → Requirement (L5). If not in EARS, flag needs-EARS-rewrite.
6. Is it a top-down ordered sequence of business functions? → Business Process / Flow (L6). If not in Mermaid TD, flag needs-mermaid-normalization.
7. Is it a user-invokable unit of behavior with internal branching (gateways, paths)? → Business Function (L7). If not in BPMN, flag needs-BPMN-normalization.
8. Is it a concrete path through a Business Function — a single user goal with scenarios? → Use Case (L8). If the assertion is not in Gherkin, flag needs-gherkin-rewrite.
9. None of the above → tag as unclassified and surface it to the user — do not silently drop or invent a node.

---

Organization Protocol (input list)

Given a heterogeneous input list, build the tree coarse-before-fine, structure-before-content.

1. Confirm the System (L1). One root. Reconcile naming with the user.
2. Identify Functional Domains (L2). Read the entire corpus and extract candidate Domains. Reconcile synonyms with the user before going further — Domain names propagate everywhere.
3. Decide per-Domain whether to introduce Sub-Domains (L3). Apply the Sub-Domain decision rule. When a Domain qualifies, place its Sub-Domains; otherwise skip L3 for that Domain. Mixed mode is allowed: Domain A can have Sub-Domains while Domain B does not.
4. Place Capabilities (L4) under their Sub-Domain when L3 exists, otherwise directly under their Functional Domain.
5. Place Requirements (L5) under each Capability. Mark non-EARS statements needs-EARS-rewrite.
6. Place Business Processes / Flows (L6) under the Requirements they satisfy. Author or normalize to Mermaid TD.
7. Decompose each Process into Business Functions (L7). Author or normalize to BPMN 2.0.
8. Enumerate Use Cases (L8) — one per BPMN path through a Business Function. Author scenarios in Gherkin.
9. Validate every leaf has a parent. No orphan nodes. No cycles.
10. Surface gaps — a Capability without Requirements, a Requirement without a Process, a Process without Business Functions, a Business Function without Use Cases, a Use Case without Gherkin scenarios — and report them. Gaps are deliverables, not failures.

---

Output Conventions

When a fragment is classified, emit it in this canonical form so downstream skills can parse it uniformly:

- id: <stable-slug>
  level: L1 | L2 | L3 | L4 | L5 | L6 | L7 | L8 | unclassified
  name: <human-readable>
  parent: <id of parent on the spine>          # L4 Capability: parent is L3 Sub-Domain when present, else L2 Functional Domain
  source: <verbatim quote or doc-anchor>       # always preserve provenance
  convention-flags:                            # optional
    - needs-EARS-rewrite                       # L5 only
    - needs-mermaid-normalization              # L6 only
    - needs-BPMN-normalization                 # L7 only
    - needs-gherkin-rewrite                    # L8 only

• source is mandatory — every node must trace back to a verbatim fragment of the original input. No invented content.
• convention-flags declare format debt; downstream agents may act on them or surface to the user.

---

Anti-patterns

• ❌ Inventing a Domain, Sub-Domain, or Capability to make an orphan fit. Use unclassified and surface it.
• ❌ Introducing a Sub-Domain (L3) when the Domain has a single team / single regulatory regime / few Capabilities. The L3 layer is optional — skip it unless the decision rule is met.
• ❌ Forcing every Capability under an L3 Sub-Domain "for symmetry" when other Domains in the same system don't need one. Mixed mode is the expected case.
• ❌ Collapsing a Business Process into a Business Function because both "describe behavior". A Process orders Business Functions; a Business Function branches into Use Cases.
• ❌ Promoting a Use Case scenario to a Business Function because it is long. Length is not a level signal.
• ❌ Re-typing the same Business Function under several Processes. Attach once, reference many.
• ❌ Authoring a Requirement in prose. Keep the prose, flag needs-EARS-rewrite, surface it.
• ❌ Authoring a Use Case as free-text acceptance criteria. Convert to Gherkin or flag needs-gherkin-rewrite.
• ❌ Silently merging two Domains with similar names. Always reconcile with the user first.

---

Why this matters

Every downstream lens — functional rules, technical contracts, UI flows, NFRs, test cases — is anchored to a node in this tree. If two analysts disagree on what a fragment is, their outputs cannot be cross-referenced and the coverage-checker cannot validate the system. The tree and the per-layer authoring conventions (EARS / Mermaid TD / BPMN / Gherkin) are the shared coordinate system that makes multi-lens analysis composable.