edercnj/x-internal-select-knowledge

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

Skill: x-internal-select-knowledge

Purpose

Resolve the canonical set of knowledge assets for a given knowledge_kind:

• technical — impacts architecture and development planning. Selected by lifecycle --phase (plan|implement|review) + active capabilities.
• domain — impacts feature/story authoring. Selected by --stage (ideate|refine|story|feature) + segment/product.

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

This is the knowledge counterpart of x-internal-select-context-packs (which handles patterns). It is deliberately separate so the patterns critical path (arch_questions, scoring_summary, conflict-groups) is never coupled to knowledge selection. Knowledge has no arch_questions, no scoring, and no conflict-groups.

Triggers

Used only through inline invocation:

Skill(skill: "x-internal-select-knowledge",
      args: "--kind domain --stage feature --segment payments")

Skill(skill: "x-internal-select-knowledge",
      args: "--kind technical --phase plan --capabilities java,security")

Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | --kind | Yes | technical or domain | | --phase | When --kind technical | plan, implement, or review | | --stage | When --kind domain | ideate, refine, story, or feature | | --capabilities | No | Comma-separated capabilities (technical match): java,api,database,security,... | | --segment | No | Comma-separated product segments (domain match): payments,lending,... | | --product | No | Comma-separated products (domain match): pix,card-issuing,... | | --grouper | No | Filter to a specific grouper (default: include shared + project groupers) | | --include-optional | No | Include assets with mandatory: optional |

Discovery and Merge Algorithm

Layer A — Knowledge Catalog Discovery (filesystem-based)

1. Glob all knowledge-catalog.md files:

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

2. For each file, read the YAML frontmatter (stop at the second ---).
3. Filter catalogs by ALL of the following:
   • artifact: knowledge-catalog (ignore files without this field).
   • status != removed and status != deprecated (unless --include-optional and status == deprecated).
   • knowledge_kind == --kind.
   • Axis filter (depends on --kind):
     • --kind technical: load_phase list intersects --phase, AND 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 in x-internal-select-context-packs).
     • --kind domain: lifecycle_stage list intersects --stage, AND domain match (any of):
       • segment is empty [] (cross-cutting), or
       • segment intersects --segment, or
       • product intersects --product, or
       • grouper is shared.
   • Grouper match: default includes all groupers found in src/patterns/, unless --grouper restricts to a specific one.
4. Map mandatory to bucket:
   • mandatory: required → required
   • mandatory: recommended → recommended
   • mandatory: optional → optional (only when --include-optional)
5. Emit the catalog path (path to the knowledge-catalog.md file itself) in its bucket.

Step 6 — Catalog Dependency Chain Resolution (depends-on):

After the initial catalog set is resolved, expand it by following depends-on declarations (format {grouper}/{knowledge-catalog}):

1. For each active catalog, read depends-on. For each referenced catalog not yet active:
   • Resolve its path: src/knowledge/{grouper}/{knowledge-catalog}/knowledge-catalog.md.
   • Add to the active set with the SAME (never lower) bucket as the dependent catalog (required > recommended > optional).
   • Recursively process its own depends-on.
2. Repeat to fixpoint. Cycle guard: maintain a visited set; on repeat, skip and log [WARN] cycle detected in knowledge depends-on: {path}.

Note: knowledge has no conflict-groups. There is no conflict-detection pass.

Layer B — Knowledge Item Resolution with depends-on Evaluation

For each active catalog resolved in Layer A:

1. Read knowledge_items list from the catalog's frontmatter.
2. For each item name, derive its path:

   {catalog_dir}/{knowledge-item-name}/knowledge.md
   

3. Read the item's frontmatter to retrieve depends-on and load_scope.
4. Evaluate load_scope:
   • load_scope: baseline → include whenever the parent catalog is active.
   • load_scope: stage → include ONLY if the item's load_phase/lifecycle_stage intersects the requested --phase/--stage.
5. Evaluate depends-on (executable — skip item if not satisfied):
   • Each dep is {grouper}/{knowledge-catalog} or {grouper}/{knowledge-catalog}/{knowledge-item}.
   • If ALL deps are present in the active set → include item in the SAME bucket as its parent catalog.
   • If ANY dep is unsatisfied → skip; log [SKIP] {path}: depends-on not satisfied ({unresolved-dep}).

Final Merge Rules

1. Union all buckets 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.

There is no Layer C/D: knowledge carries no arch_questions and no scoring_summary.

Output Contract

{
  "kind": "domain",
  "stage": "feature",
  "phase": null,
  "segment": ["payments"],
  "product": [],
  "capabilities": [],
  "required": [
    "src/knowledge/shared/refinement-decomposition/knowledge-catalog.md",
    "src/knowledge/shared/refinement-decomposition/decomposition-guide/knowledge.md"
  ],
  "recommended": [],
  "optional": [],
  "deprecated": []
}

For --kind technical, phase is set and stage is null:

{
  "kind": "technical",
  "phase": "plan",
  "stage": null,
  "capabilities": ["security"],
  "segment": [],
  "product": [],
  "required": [
    "src/knowledge/shared/governance-baselines/knowledge-catalog.md",
    "src/knowledge/shared/governance-baselines/quality-gates/knowledge.md",
    "src/knowledge/shared/security-knowledge/knowledge-catalog.md"
  ],
  "recommended": [],
  "optional": [],
  "deprecated": []
}

Compatibility rules:

• kind, required, recommended, optional, deprecated are stable and mandatory.
• required and recommended contain both knowledge-catalog.md and knowledge.md item paths — consumers read all paths.
• Same bucket shape as x-internal-select-context-packs, so consumers can union results from both selectors and run a single "Read every path" loop.

Consumer Contract

Caller skills MUST:

1. Invoke this skill once during context-loading, in addition to (not instead of) x-internal-select-context-packs.
2. Read all paths in required (both knowledge-catalog.md and knowledge.md files).
3. Read recommended when relevant to the current scope.
4. Never hardcode knowledge paths when an equivalent catalog/item row exists.

Domain consumers (x-create-feature, x-refine-feature, x-internal-create-feature, x-add-story-to-feature) call with --kind domain --stage <stage> + the active --segment/--product.

Technical consumers (x-plan-architecture, x-internal-plan-arch-story, x-plan-story, x-plan-task, x-implement-*, x-review-*) call with --kind technical --phase <phase> + the active --capabilities.

Error Handling

| Scenario | Action | |----------|--------| | No knowledge-catalog.md files found | Return empty arrays with INFO note; caller continues | | --kind missing or invalid | Abort: KNOWLEDGE_KIND_INVALID | | --kind technical without --phase | Abort: KNOWLEDGE_PHASE_REQUIRED | | --kind domain without --stage | Abort: KNOWLEDGE_STAGE_REQUIRED | | 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 (item level) | Skip item; log [SKIP] {path}: depends-on not satisfied ({dep}); do not abort | | depends-on chain cycle (catalog level) | Log [WARN] cycle detected; break cycle; do not abort |