map-explain

$map explain <target>

Explain a specific function, capability, or schema element in domain terms using the committed coco-map.json. Answers: what it does, what depends on it, what it depends on, and how it relates to the nearest business capability.

Preconditions

• .cocoplus/ must be initialized
• .cocoplus/map/coco-map.json must exist (run $map first)
• <target> argument must be provided

Arguments

• <target> (required): A function name, business capability name, or schema element name to explain. Case-insensitive matching is applied.

Step-by-Step Behavior

1. Verify initialization: Check .cocoplus/ exists. If not, output: "CocoPlus not initialized. Run $pod init first." and exit.

2. Verify map exists: Check .cocoplus/map/coco-map.json exists. If not, output:

   No function knowledge graph found. Run $map first to build it.
   

   and exit.

3. Read coco-map.json: Load all structural and domain sections.

4. Locate target: Search for <target> across:

   • Function names in structural.functions
   • Capability names in domain.capabilities
   • Vocabulary terms in domain.vocabulary
   • Apply case-insensitive fuzzy match (substring match if exact match not found)

5. If not found: Output:

   No function or capability named '[target]' found in coco-map.json.
   Available functions: [comma-separated list]
   Available capabilities: [comma-separated list]
   Run $map to refresh the map if the project has changed.
   

   and exit.

6. Build explanation depending on target type:

For a function:

[function-name] — Cortex AI Function
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What it does:
  [domain-level description from domain.vocabulary and domain.capabilities]
  Cortex API: [AI_CLASSIFY / AI_COMPLETE / etc.]
  File: [file-path]
  Schema: [database.schema.function-name]

Business capability:
  [nearest capability from domain.capabilities, or "Not associated with a named capability"]

Dependencies (what it depends on):
  Direct: [list of functions/tables this function depends on]
  Transitive: [second-level dependencies if notable]
  [or: "No upstream dependencies"]

Dependents (what depends on it):
  Direct: [list of functions that call or depend on this one]
  Transitive: [downstream functions up to 3 hops]
  [or: "No downstream dependents — this is a leaf function"]

Evaluation coverage:
  [Evaluation set name and baseline accuracy if available, or "No evaluation baseline — Gap detected"]

Last analyzed: [timestamp from coco-map.json meta.generated_at]