edercnj/x-internal-select-context-packs

🔒 INTERNAL SKILL Invoked only by orchestrator/specialist skills to avoid duplicated hardcoded KP lists.

Skill: x-internal-select-context-packs

Purpose

Resolve the canonical set of patterns and knowledge assets for a given lifecycle phase (plan, implement, review) and active capabilities (for example: java, api, database, security).

Additionally, after resolving the asset list, this skill extracts frontmatter metadata to produce:

• arch_questions_by_category: aggregated architecture interview questions for x-plan-architecture skills
  • Source: catalog.md files ONLY (artifact: catalog). Sub-pattern pattern.md files NEVER have arch_questions.
• scoring_summary: aggregated scoring config for x-review-* and x-audit-code skills
  • Source: sub-pattern pattern.md files ONLY (artifact: sub-pattern).

The selection source of truth is the filesystem: catalog.md files discovered via glob under src/patterns/.

This skill enforces consistency between planning, implementation, and review by centralizing selection logic in one place.

Triggers

Used only through inline invocation:

Skill(skill: "x-internal-select-context-packs",
      args: "--phase review --capabilities java,api,security,database")

Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | --phase | Yes | plan, implement, or review | | --capabilities | Yes | Comma-separated capabilities (java,api,database,security,...) | | --grouper | No | Filter to a specific grouper. When omitted, all groupers found in src/patterns/ are eligible. | | --include-optional | No | Include assets with mandatory: optional | | --no-metadata | No | Skip Layer D (frontmatter extraction); omits arch_questions_by_category and scoring_summary from output |

Integration Contract (Central Tech Evaluation)

This skill MUST attempt a single inline invocation of:

Skill(skill: "x-internal-evaluate-tech-context",
      args: "--phase <phase> --capabilities <capabilities> [--include-optional]")

Where:

• <phase> is the same value received by this skill (plan|implement|review).
• <capabilities> is forwarded without semantic change.
• --include-optional is forwarded when present.

No additional skill integrations are required in this scope.

Discovery and Merge Algorithm

Layer A — Catalog Discovery (filesystem-based)

Replaces legacy CSV-based asset matrix. No CSV files are used.

1. Glob all catalog.md files under src/patterns/:

   find src/patterns -name "catalog.md" -type f
   

2. For each catalog.md, read the YAML frontmatter (stop at second ---).
3. Filter catalogs by ALL of the following:
   • artifact: catalog (ignore files without this field)
   • status != removed and status != deprecated (unless --include-optional and status == deprecated)
   • load_phase list intersects the requested --phase
   • Capability match (any of):
     • scope includes shared, or
     • grouper is shared, or
     • stack list intersects at least one requested capability, or
     • type value maps to a requested capability (see Capability–Type mapping table)
   • Grouper match: when --grouper is provided, only catalogs with matching grouper value; when omitted, all catalogs passing the other filters are included
4. Map mandatory to bucket:
   • mandatory: required → required
   • mandatory: recommended → recommended
   • mandatory: optional → optional (only when --include-optional)
5. Emit catalog path in bucket (path to the catalog.md file itself).
6. Track selection origin for every catalog added in steps 1–5: record it in directly_matched set. This is used by Layer D1 to distinguish direct questions from inherited questions.

Step 6 — Catalog Dependency Chain Resolution (new for catalog-level depends-on):

After the initial catalog set is resolved in steps 1–5, expand it by following depends-on declarations in each active catalog's frontmatter:

1. For each active catalog (visit in order of discovery): a. Read depends-on list from frontmatter (format: {grouper}/{catalog}, e.g. my-project/java11). b. For each referenced catalog path not yet in the active set:
   • Resolve its catalog.md path: src/patterns/{grouper}/{catalog}/catalog.md
   • Add to the active set with the SAME bucket as the dependent catalog (never downgrade: required > recommended > optional).
   • Mark this catalog as chain_inherited (NOT in directly_matched) — this marking is used by Layer D1.
   • Record chain_source: {dependent-catalog-path} for traceability.
   • Recursively process the newly added catalog's own depends-on.
2. Repeat until no new catalogs are added (fixpoint — typically 3–4 iterations for the Java chain).
3. Cycle guard: maintain a visited set; if a catalog path was already visited, skip it to avoid infinite loops. Log [WARN] cycle detected in catalog depends-on: {path}.

Version chain example: Activating my-project/java25 → loads my-project/java21 (via depends-on, chain_inherited) → loads my-project/java11 (via depends-on, chain_inherited). Sub-patterns from all catalogs are included; no duplication.

Bucket precedence: If a catalog appears both directly (from capability match) and via a dependency chain, use the higher-priority bucket AND mark it as directly_matched (direct wins over inherited).

Capability–Type mapping table (used in step 3 capability match):

| Requested capability | Matched catalog type values | |----------------------|-------------------------------| | java | language, framework with stack: [java] | | spring | framework with stack: [spring] | | api | api | | database | database | | cache | cache | | security | security | | architecture | architecture | | aws / cloud | cloud | | infra | infra | | observability | observability | | testing | testing | | product | product | | planning | planning | | ai-kit-tools | ai-kit-tools |

Step 7 — Conflict Detection:

After the catalog set is fully resolved (Steps 1–6), scan for mutual exclusion violations:

conflict_warnings = []

# Pass A: conflict-group duplicates
group_map = {}
for catalog in ACTIVE_CATALOGS:
  g = catalog.frontmatter.get("conflict-group", "")
  if g != "":
    group_map[g] = group_map.get(g, []) + [catalog]

for group, members in group_map.items():
  if len(members) > 1:
    directly_selected = [c for c in members if c in directly_matched]
    if len(directly_selected) > 1:
      # Only warn when >1 was EXPLICITLY selected (not just chain-inherited)
      severity = members[0].frontmatter.get("conflict-severity", "warning")
      conflict_warnings.append({
        "type": "conflict-group",
        "severity": severity,
        "group": group,
        "catalogs": [c.key for c in members],
        "directly_selected": [c.key for c in directly_selected],
        "message": f"Conflict group '{group}': only ONE catalog should be active — found: {[c.key for c in directly_selected]}"
      })

# Pass B: explicit conflicts-with
checked = set()
for catalog in ACTIVE_CATALOGS:
  for ref in catalog.frontmatter.get("conflicts-with", []):
    pair = tuple(sorted([catalog.key, ref]))
    if pair not in checked and ref in ACTIVE_CATALOGS:
      checked.add(pair)
      severity = catalog.frontmatter.get("conflict-severity", "warning")
      conflict_warnings.append({
        "type": "explicit",
        "severity": severity,
        "catalogs": [catalog.key, ref],
        "message": f"'{catalog.key}' declares incompatibility with '{ref}'"
      })

# Pass C: sub-pattern conflict-group duplicates (within same catalog)
for catalog in ACTIVE_CATALOGS:
  sub_group_map = {}
  for sub in catalog.active_sub_patterns:
    g = sub.frontmatter.get("conflict-group", "")
    if g != "":
      sub_group_map[g] = sub_group_map.get(g, []) + [sub]
  for group, subs in sub_group_map.items():
    if len(subs) > 1:
      severity = subs[0].frontmatter.get("conflict-severity", "warning")
      conflict_warnings.append({
        "type": "sub-pattern-conflict-group",
        "severity": severity,
        "group": group,
        "catalog": catalog.key,
        "sub_patterns": [s.name for s in subs],
        "message": f"[{catalog.key}] Sub-pattern conflict group '{group}': only ONE sub-pattern should be active — found: {[s.name for s in subs]}"
      })

Output: conflict_warnings is added to the final output object (empty array = no conflicts).

Note: Chain-inherited catalogs that form a conflict-group are expected (e.g. java/java11/java21/java25 all have conflict-group: java-version but only ONE was directly selected — the chain adds the others). Conflict is only flagged when multiple catalogs from the same group were directly selected (not chain-inherited).

Layer B — Sub-pattern Resolution with depends-on Evaluation

For each active catalog resolved in Layer A:

1. Read sub_patterns list from the catalog's frontmatter (list of sub-pattern names).
2. For each sub-pattern name, derive its path:

   {catalog_dir}/{sub-pattern-name}/pattern.md
   

3. Read the sub-pattern's frontmatter to retrieve depends-on.
4. Evaluate depends-on (executable — skip sub-pattern if not satisfied):
   • Each dep is either {grouper}/{catalog} (catalog-level) or {grouper}/{catalog}/{sub-pattern} (sub-pattern-level).
   • For each dep: check if the referenced catalog (or sub-pattern) is present in the active set resolved so far.
   • If ALL deps satisfied → include sub-pattern in the SAME bucket as its parent catalog.
   • If ANY dep is NOT satisfied → skip sub-pattern (do NOT include in any bucket); log: [SKIP] {path}: depends-on not satisfied ({unresolved-dep}).
5. If sub-pattern has no depends-on field (or empty list) → always include if parent catalog is active.

Important: depends-on is evaluated AFTER Layer A completes, using the full active catalog set.

Layer C — Central Evaluator Asset Overlay

Merge selectedAssets from x-internal-evaluate-tech-context (when available):

• selectedAssets.required → required
• selectedAssets.recommended → recommended (unless already required)
• selectedAssets.optional → optional only when --include-optional

If central evaluation fails or times out: proceed with Layers A+B only; add diagnostic rationale.

Final Merge Rules (deterministic and backward compatible)

1. Union all layers using precedence: required > recommended > optional.
2. Deduplicate asset paths across all buckets.
3. Never emit status: removed or status: deprecated assets in active buckets.
4. Populate deprecated only with assets explicitly marked status: deprecated that were matched.
5. Sort each bucket ascending by asset_path.

Layer D — Frontmatter Metadata Extraction (arch_questions + scoring)

Skip this layer when --no-metadata flag is present.

After computing the final merged asset list (Layers A+B+C), split paths by artifact type:

D1 — arch_questions (from catalog.md files only):

1. For every catalog.md path in required ∪ recommended:
   • Read arch_questions array from frontmatter.
   • Add source_asset field = catalog path to each question.
   • Add inherited: true if the catalog is in chain_inherited set (loaded via depends-on chain, NOT directly matched by capability). Otherwise inherited: false.
   • Add chain_source field if inherited: true (the catalog that triggered loading this one).
2. Group all collected questions by category letter → arch_questions_by_category.
3. Deduplicate by id (first occurrence wins; direct-match questions take precedence over inherited ones with the same ID).
4. Do NOT read arch_questions from sub-pattern pattern.md files — they never have this field.

Inherited question semantics for consumers:

• inherited: false → question belongs to a directly selected technology; always ask if unanswered.
• inherited: true → question belongs to a parent version/catalog loaded automatically via chain:
  • If already answered in a parent artifact (product/capability) AND inheritable: true → skip (auto-fill from parent answer).
  • If NOT yet answered anywhere → ask normally (the decision is still relevant for the current scope).
  • If answered with a conflicting value vs the current chain context → log [WARN] version-chain inconsistency and re-ask to confirm.

Version-chain consistency rule (mandatory for version catalogs): If a question with id matching *-P-01 category L (version selection) has been answered in parent context AND the chain-inherited catalog is a different version than the answer, emit a consistency warning in the output:

{
  "version_chain_warnings": [
    {
      "question_id": "JAVA-P-01",
      "answered_value": "Java 21 (LTS - recomendado)",
      "chain_context": "my-project/java25 is active but JAVA-P-01 answer indicates Java 21",
      "recommendation": "Re-confirm version selection: Java 25 was loaded via depends-on chain"
    }
  ]
}

D2 — scoring_summary (from sub-pattern pattern.md files only):

1. For every pattern.md sub-pattern path in required ∪ recommended with scoring_enabled: true:
   • Read max_positive_score, max_negative_score, go_nogo_threshold_pct, go_with_reservations_pct.
2. Build scoring_summary:
   • assets_scored: list of pattern.md paths with scoring enabled
   • total_max_positive_score: sum of all max_positive_score
   • total_max_negative_score: sum of all max_negative_score
   • go_nogo_threshold_pct: minimum threshold across assets (most strict)
   • go_with_reservations_pct: minimum threshold across assets (most strict)

Performance rule: Read catalog.md frontmatters in bulk (parallel reads) for all resolved paths. Use x-internal-extract-asset-metadata for sub-pattern files.

Error isolation: If metadata extraction fails for a specific asset, skip that asset's contribution. Do NOT abort.

Output Contract

Baseline output (always present — backward compatible)

{
  "phase": "review",
  "capabilities": ["java", "api", "security"],
  "required": [
    "src/patterns/shared/architecture/catalog.md",
    "src/patterns/shared/architecture/hexagonal/pattern.md",
    "src/patterns/shared/security/catalog.md",
    "src/patterns/shared/security/java/pattern.md"
  ],
  "recommended": [
    "src/patterns/shared/api/catalog.md",
    "src/patterns/shared/api/rest/pattern.md"
  ],
  "optional": [],
  "deprecated": []
}

Extended output (added by Layer D — non-breaking)

{
  "phase": "plan",
  "capabilities": ["java", "api", "architecture"],
  "required": ["..."],
  "recommended": ["..."],
  "optional": [],
  "deprecated": [],
  "arch_questions_by_category": {
    "C": [
      {
        "id": "ARCH-HEX-01",
        "category": "C",
        "question": "What architectural style will be applied to this service?",
        "choices": ["Hexagonal (Ports and Adapters)", "Clean Architecture", "Onion Architecture"],
        "mandatory": true,
        "inheritable": true,
        "phase": "plan",
        "source_asset": "src/patterns/shared/architecture/catalog.md"
      }
    ],
    "N": [
      {
        "id": "JAVA21-P-01",
        "category": "N",
        "question": "Will Virtual Threads (Project Loom) be enabled in this service?",
        "choices": ["Yes (spring.threads.virtual.enabled: true — recommended for I/O-bound)", "No"],
        "mandatory": true,
        "inheritable": true,
        "phase": "plan",
        "source_asset": "src/patterns/my-project/java21/catalog.md",
        "inherited": true,
        "chain_source": "src/patterns/my-project/java25/catalog.md"
      }
    ]
  },
  "version_chain_warnings": [],
  "conflict_warnings": [],
  "scoring_summary": {
    "assets_scored": [
      "src/patterns/shared/architecture/hexagonal/pattern.md",
      "src/patterns/shared/security/java/pattern.md"
    ],
    "total_max_positive_score": 68,
    "total_max_negative_score": -55,
    "go_nogo_threshold_pct": 80,
    "go_with_reservations_pct": 65
  }
}

Compatibility rules:

• phase, capabilities, required, recommended, optional, deprecated remain stable and mandatory.
• arch_questions_by_category and scoring_summary are additive — consumers that ignore unknown fields continue to work unchanged.
• When --no-metadata is passed, arch_questions_by_category and scoring_summary are omitted (not null).
• required and recommended now contain both catalog.md and pattern.md paths (consumers should read all paths in these arrays).

Optional non-breaking diagnostic fields MAY be included when central evaluation is available:

{
  "techProfile": {
    "phase": "review",
    "capabilities": ["java", "api", "security"],
    "detectedDomains": ["api-events", "security"]
  },
  "skipped_sub_patterns": [
    { "path": "...", "reason": "depends-on my-project/java21 not active" }
  ],
  "gaps": [],
  "rationale": []
}

Consumer Contract

Caller skills MUST:

1. Invoke this skill once during context-loading.
2. Read all paths in required (both catalog.md and pattern.md files).
3. Read recommended when relevant to current scope.
4. Never hardcode duplicate list blocks when an equivalent catalog/sub-pattern row exists.

Dynamic-mode consumers (x-plan-architecture, x-review-*) SHOULD additionally:

5. Read arch_questions_by_category to build the architecture interview question set (when phase = plan).
   • These questions come ONLY from catalog.md files; never from sub-pattern pattern.md files.
6. Read scoring_summary to configure GO/NO-GO thresholds (when phase = review or x-audit-code).
   • These scores come ONLY from sub-pattern pattern.md files.
7. Fall back to built-in essential questions/thresholds if arch_questions_by_category or scoring_summary is absent.

Fallback protocol for arch_questions_by_category:

IF arch_questions_by_category is absent OR empty:
  → Use ESSENTIAL_QUESTIONS set (built into each x-plan-architecture skill)
  → Log: "[WARN] No arch_questions found in selected catalogs. Using built-in essential questions."
ELSE:
  → Merge ESSENTIAL_QUESTIONS with dynamic questions.
  → Dynamic questions override essential questions with the same ID.
  → Ask essential questions for any category not covered by dynamic questions.

Language Capability Detection Signals

Callers (typically x-internal-evaluate-tech-context) derive capabilities from project file signals:

| Capability | Primary Signal | Secondary Signal | |------------|---------------|-----------------| | java | pom.xml or build.gradle | *.java files | | api | REST controller annotations | OpenAPI spec files | | database | JPA/repository annotations | application.yml datasource config | | security | Spring Security dependency | OAuth/JWT config | | aws | AWS* SDK dependency | application.yml aws config | | testing | JUnit/Mockito dependencies | src/test/** files |

Error Handling

| Scenario | Action | |----------|--------| | No catalog.md files found | Return empty arrays with INFO note; caller may continue with domain fallback | | Invalid phase | Abort: ASSET_PHASE_INVALID | | No assets matched | Return empty arrays with INFO note | | Malformed catalog frontmatter | Skip that catalog; log [WARN] malformed frontmatter: {path}; do not abort | | depends-on not satisfied (sub-pattern level) | Skip sub-pattern; log [SKIP] {path}: depends-on not satisfied ({dep}); do not abort | | depends-on chain cycle (catalog level) | Log [WARN] cycle detected in catalog depends-on: {path}; break cycle; do not abort | | Central evaluation fails | Do not abort; execute Layers A+B only and preserve output contract | | Layer D metadata extraction fails for one or more assets | Do not abort; skip failed assets; include available metadata from successful extractions |