/pair-capability-map-subdomains — Subdomain Placement (Capability)

Classify business capabilities into Domain-Driven Design subdomains — core, supporting, or generic — and place them with a Volatility rating. A capability, not a standalone lifecycle step: always invoked scoped to the items the caller just touched, never as a full re-mapping outside /pair-process-bootstrap.

Process Profile

<!-- process-step: id=define-subdomains -->

Executable form of the define-subdomains step. A direct invocation while a step is disabled by the project's profile warns and asks for confirmation; under $approval: auto there is nobody to answer, so the run HALTs. <!-- approval-round: kind=gate; auto=halt -->

A composed invocation never prompts — it degrades exactly as a step that is not installed. No section ⇒ no-op. See process-profile gate.

Arguments

Argument	Required	Description
$scope	Yes	Items/areas touched by the caller (e.g. capability names, PRD sections, an initiative). all — full re-mapping, allowed only when composed by /pair-process-bootstrap.
$approval	No	Approval-round mode: interactive (default — the Step 3 round runs as written) or auto (ask nothing: the proposed placement is accepted as-is, a conflict keeps the existing entry, and both are reported). See approval rounds.

Composed Skills

Caller	When
/pair-process-refine-story	Functional/domain analysis phase — placement for the story's capability.
/pair-process-plan-initiatives	Domain placement for a new initiative's capability area.
/pair-process-plan-epics	Domain placement for an epic's capability area.
/pair-process-brainstorm	Broad/functional discovery (phase 2) touching multiple capabilities.
/pair-process-bootstrap	Initial full-catalog mapping — the only caller allowed $scope: all.

Invocable independently with an explicit $scope for ad hoc placement.

Algorithm

Step 0: Resolve Scope and DDD Adoption State

1. Check: Does adoption/product/subdomain/ contain .md files beyond README.md (DDD already adopted)?
2. Check: If not adopted, are PRD and initiatives available (business context to classify from)?
   • PRD: .pair/adoption/product/PRD.md
   • Initiatives: query PM tool or check adoption files
3. Act: Resolve the working mode:
   • DDD mode — subdomain catalog exists, or PRD + initiatives are available for classification.
   • System-areas fallback — no subdomain catalog AND no PRD/initiatives. No DDD prerequisite is enforced; do not HALT. Proceed to Step 1 in fallback mode.
4. Check: Does $scope resolve to any item in the current context?
5. Skip: If $scope resolves to nothing → report "no domain impact" and return control to the caller. No file changes.
6. Verify: Mode and non-empty scope determined.

Step 1: Detect Existing Subdomains

1. Check: Scan adoption/product/subdomain/ for existing .md files (excluding README.md).

2. Act: Build a registry of existing subdomains:

   EXISTING SUBDOMAINS:
   ├── [filename.md]: [Title] (Classification: [Core/Supporting/Generic], Volatility: [High/Medium/Low])
   └── ...
   

3. Verify: Registry built. Only entries touched by $scope are candidates for creation/update; the rest are left untouched.

Step 2: Business Capability Analysis (DDD mode)

Skip if in system-areas fallback — go to Step 2b.

1. Act: Analyze the capabilities in $scope (or the full PRD/initiatives set when $scope: all, bootstrap only):
   • Extract business function from PRD objectives and value propositions.
   • Map the touched initiative(s)/epic(s)/story to a business capability area.
   • Identify cross-cutting concerns and shared functionality patterns relevant to the scope.
2. Verify: Business capabilities in scope identified.

Step 2b: System-Areas Fallback (no-DDD projects)

1. Act: Instead of business-capability analysis, derive placement from the codebase's existing structure: top-level packages/apps/services/modules touched by $scope.
2. Act: Treat each system area as a placeholder subdomain with Classification: Generic and Volatility: Low unless the caller has clear evidence otherwise — these are provisional, not a DDD classification.
3. Verify: Placement resolved to system area(s). Note in output that this is a fallback, not a DDD classification, and that /pair-process-bootstrap or a full /pair-capability-map-subdomains run can upgrade it later.

Step 3: DDD Classification, Volatility & Catalog Delta

Skip if in system-areas fallback — the Classification/Volatility already assigned in Step 2b (Generic/Low unless the caller has clear evidence otherwise) is final for this run; go straight to Step 4.

1. Act (DDD mode): Classify each in-scope capability:

   • Core — competitive advantage, high business value, high complexity. Build in-house, invest deeply. Default Volatility: High.
   • Supporting — operational necessity, medium value. Important but not differentiating. Default Volatility: Medium.
   • Generic — commodity function, low differentiation. Buy or use standard solutions. Default Volatility: Low. Additionally assess implementation volatility — the probability of switching provider/technology; when High, note that relationships toward this subdomain require an integration contract (feeds /pair-capability-map-contexts strength assessment).

2. Act: Volatility default follows the classification above; the developer may override it (business-domain judgment, never inferred from commit history alone).

3. Act: Map relationships and data flow between in-scope subdomains and their existing dependencies.

4. Check: Does an in-scope subdomain already exist in the registry with a different classification, or a different Volatility that was not recorded as a human override? Compare against the existing file's recorded values, not a freshly-recomputed classification-derived default — a Volatility that already carries an override reason is never treated as conflicting with that same default recomputed again; only a change to classification, or an explicit new override request, is a conflict.

5. Act: If a conflict exists → propose the delta only (not a full re-map):

   Existing: [Name] — Classification: [X], Volatility: [Y] Proposed: Classification: [X'], Volatility: [Y'] Approve delta, keep existing, or override? <!-- approval-round: kind=keep-or-redo; auto=keep -->

   Under $approval: auto this question is not asked and the existing entry is kept — the conservative branch it already offers. The unapplied delta is reported (Output Format) so nothing is lost; overwriting a recorded classification nobody was asked about is the one outcome auto must not produce.

6. Act: Present the scoped catalog delta to the developer ($approval: interactive; under auto it is reported in the Output Format instead of asked):

   Proposed subdomain placement (scope: [$scope]): [Classification]: [Name] — Volatility: [Level] ([default | override: reason])

   Relationships: [key dependencies within scope] Approve or adjust? <!-- approval-round: kind=confirm; auto=accept -->

7. Verify ($approval: interactive): Developer approves the delta. Under auto the delta is accepted as-is (already reported in item 6) and Step 4 writes it — except a conflict from item 5, which stays unapplied. <!-- approval-round: kind=confirm; auto=accept -->

Step 4: Subdomain Specification

For each approved subdomain in scope:

1. Check: Does this subdomain already exist as a file?
2. Act: If exists and no conflict was raised → leave untouched; pre-existing entries without a Volatility field remain valid as-is (no forced migration — the field is added the next time this entry falls inside a $scope).
3. Act: If new, or an approved delta applies → create/update the subdomain file following subdomain-template.md (resolve override-first — template resolution):
   • Fill all template sections: Classification, Volatility, Business Purpose, Key Capabilities, Strategic Importance, Complexity Assessment, Data Ownership, Dependencies, Team Recommendations, Implementation Priority.
   • File path: adoption/product/subdomain/[kebab-case-name].md
4. Verify: File created/updated and parseable. Entries outside $scope are untouched.

Step 5: Update Catalog README

1. Act: Update adoption/product/subdomain/README.md for the entries touched by this run:
   • List all subdomains by classification (Core, Supporting, Generic), with Volatility.
   • Include links to individual files.
   • Update the Subdomain Relationship Matrix for affected entries only.
2. Verify: README reflects the current catalog.

Output Format

SUBDOMAIN PLACEMENT COMPLETE:
├── Scope:      [$scope]
├── Mode:       [DDD | System-areas fallback]
├── Touched:    [N subdomains]
├── Created:    [X new files]
├── Updated:    [Y existing files]
├── Volatility: [defaults applied: A, overridden: B]
├── Approval:   [interactive — approved | auto — accepted as-is, C conflict(s) kept unapplied]
├── Location:   adoption/product/subdomain/
└── Next:       /map-contexts (scoped to the same items)

The Next: line names only steps enabled by the project's process profile: a disabled one is dropped, and when none is left the line names no skill.

Edge Cases and Error Handling

• Scope resolves to nothing — report "no domain impact", caller proceeds without HALT.
• Existing catalog conflicts with scoped update — always propose the delta and require human approval before writing (idempotent behavior preserved). Under $approval: auto the write does not happen either: the existing entry is kept and the delta is reported unapplied (Step 3 item 5). <!-- approval-round: kind=keep-or-redo; auto=keep -->
• Pre-existing files without Volatility — treated as valid; field is added only when that entry falls inside a future $scope.
• No subdomain/ or boundedcontext/ artifacts at all — system-areas fallback (Step 2b); no error, no DDD prerequisite.
• $scope: all requested by a caller other than /pair-process-bootstrap — warn and downgrade to the caller's actual touched items; full re-mapping stays bootstrap-only.

Graceful Degradation

See graceful degradation (adoption/context inputs missing → warn, proceed with what's available rather than halting) for the standard scenarios. Additional cases:

• If initiatives are not available but PRD is, proceed with PRD-only analysis and warn.
• If neither PRD nor initiatives nor an existing catalog are available, use the system-areas fallback (Step 2b) rather than halting.
• If the adoption directory doesn't exist, create it.
• If README.md doesn't exist, create it from scratch.

Notes

• This skill creates/updates adoption files — not PM tool issues. Subdomains are design artifacts.
• Idempotent — see idempotency convention. This skill's check: detects existing files by filename; only entries inside $scope are evaluated for changes.
• Volatility is evaluated from the business domain (classification-derived default + human override), never from commit history alone.
• DDD classification and Volatility drive downstream assessments — see /pair-capability-map-contexts (relationship strength/distance/volatility) and the architecture-quality capability that consumes them.
• Migration: this skill was reclassified from a process skill (process/map-subdomains) to a capability (capability/map-subdomains) — see skills-guide.md for the rename and new invocation paths.