Decompose a process into component skills

Invoked from meta-draft-l1-skill step 6, or standalone when reviewing an existing skill's decomposition. Walk the granularity heuristic and produce a structured decomposition output the parent skill or contributor can act on.

Step 1 — list candidate units

Inside the in-progress process write-up, list every distinct unit: branching points, reusable sub-processes, document-acquisition flows, regional forks, certification paths. One unit per row; capture a short id proposal and a one-line description.

A unit is anything you can describe in a single sentence ending with "...and the user is then ready for the next step". If the description rambles or lists multiple actions, split it.

Step 2 — apply the granularity heuristic

For each candidate unit, walk the four-row table:

Record the row that fired and the rationale. If two rows conflict (e.g., the unit is referenced by two skills but only has 2 simple actions), prefer extraction — reuse wins, the cost of an extra file is low.

Step 3 — detect reuse

For each "extract" candidate, search the existing corpus for a matching component skill. If found, emit a requires pointer instead of drafting a new skill. If not found, the candidate becomes a new skill draft, recursed via meta-draft-l1-skill.

Search both the committed corpus (skills/<id>/canonical.md) and the in-flight proposals (skills/<id>/proposals/<proposal-id>/proposal.md) — a requires.id may resolve to a stable skill OR to an alpha / beta proposal_id.

Pre-draft skeletons (canonical.md with corpus_status set, no body) also count as "in catalogue" — referencing one is fine and signals the chain author's intent that this component will be drafted later.

Step 4 — check recursion depth

If extracting a component skill triggers another decomposition (the new component itself decomposes into further components), trace the depth. Flag any chain reaching depth 3. Prefer flattening unless recursion is genuinely needed; record the rationale if depth is kept.

Depth 3 fires for processes like: parent skill → origin-document component → certification-path component → translation component. Often the bottom level (translation) is shared across many origin documents — extracting it pays off; sometimes the middle level (certification path) is thin enough to inline back into the origin-document component.

Step 5 — work the branching-axes checklist

For Belgian-jurisdiction entry-point skills, walk every standard axis explicitly:

• Region — Brussels-Capital, Wallonia, Flanders. If the process forks regionally (Inburgering / Parcours d'intégration / BAPA), each branch is either a body section in the parent or a separate component skill.
• Residency status — registered_resident, family_reunification, student, posted_worker, etc. Check applies_to.residency_status on the parent.
• Civil status — single, married, married_to_belgian, cohabiting_legal, divorced, widowed. Married-to-Belgian fast-tracks under art. 12bis §1, 3° (5y residence + 3y cohabitation with Belgian spouse, lighter integration evidence) are a common fork.
• Origin country — drives apostille (Hague), legalisation (non-Hague), EU 2016/1191 (EU). One component skill per origin-document type, selected via selects_on: { origin_country: [...] } on the parent's requires entry.
• EU vs third-country national — affects document certification, residence-permit type, work-permit requirements.
• Capability tier — does the parent skill require pdf_generation, vision, or another capability that not every consumer AI has? Declare on requires_capabilities.

For each axis that forks the process, decide: does the branch live in the parent body (regional branch, often), or extract as a separate component skill (origin documents, always)? Record the body / component split per axis.

selects_on values are validated against schemas/types.json (closed enums for sponsor_type, entry_type, card_outcome, region, treaty_status, divorce_type, relationship_type, regime; open ISO-3166-1 alpha-2 for origin_country). When a new dimension or value is needed for decomposition, propose an addition to types.json as part of the draft submission.

Step 6 — apply the inline-vs-extract rubric

When the granularity heuristic gives a clear answer, take it. When the unit sits on a boundary, apply the rubric:

• Inline when: the unit is tightly coupled to surrounding context, paraphrasing it in another skill would lose meaning, and no other corpus skill is likely to need it.
• Extract when: the unit has its own input/output contract (document in, certified document out), is statutorily distinct (governed by its own law or directive), or has its own diagram complex enough to crowd the parent's process.mmd.
• Reuse when: an existing skill or in-flight proposal already does the unit. Add a requires pointer.
• Flatten when: extraction would produce a separate skill of ≤2 sentences, or when it would push recursion past depth 3 without rationale.

If the rubric still does not resolve, default to extraction. The cost of an over-decomposed corpus is one extra file; the cost of an under-decomposed corpus is duplicated content and drift.

Step 7 — produce the decomposition output

Return to the caller (meta-draft-l1-skill step 6, or the contributor) with four structured lists:

• Extract — one row per new separate skill: proposed id, category, one-line description, granularity-row that fired, recursion-depth note. Each row is a downstream draft target.
• Inline — one row per unit that stays in the parent body: body section name, granularity-row that fired.
• Reuse — one row per existing-skill pointer: requires.id, selects_on clause if conditional, granularity-row that fired.
• Branching axes — one row per axis that forks the parent: axis name, branching values, body-section vs component-skill split.

The decomposition output feeds directly into the parent's requires[] (extract + reuse rows), the parent's body structure (inline rows + branching axes that live in the body), and the parent's process.mmd (any axis with branching).

Chain absorption. When a parent skill is naturally a chain (event-triggered, sequencing several existing entry-point-shaped skills), the decomposition output's "Reuse" rows enumerate the existing skills the chain requires. The components keep their own canonical-section set; they are not extracted "from" the chain (they pre-exist) — the chain references them. Distinguish in the decomposition output: chain-references go in "Reuse"; new building blocks go in "Extract".

Verify with your commune (or relevant authority) before filing — procedures vary and change.

References