SuperAPI AI Directory

map-explain

Coding & development

View repository

Updated 10-23 23:07

About this skill

$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.
  1. 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.

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

  3. 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)
  4. 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.

  5. 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]

For a business capability:

[capability-name] — Business Capability
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

What it does:
  [description from domain.capabilities]

Functions implementing this capability:
  - [function-name]: [brief role]
  - ...

Evaluation health:
  [N of M functions have evaluation baselines]

Dependencies across functions in this capability:
  [Internal dependency structure, or "Functions in this capability are independent"]

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

For a vocabulary term:

[term] — Domain Vocabulary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Definition: [from domain.vocabulary]
Associated functions: [list]
Aliases: [if any]

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

Error Cases

  • Target not found: Output message with available functions/capabilities list and suggestion to run $map to refresh
  • coco-map.json parse error: Output warning and suggest re-running $map
  • coco-map.json missing: Redirect to run $map first

Exit Criteria

This skill is complete when:

  • Natural language explanation is displayed for the specified target
  • No files are written (this is a read-only lookup tool)

Anti-Rationalization

Do NOT:

  • Create any git commit
  • Modify coco-map.json or any other file
  • Fetch external documentation (that is CocoScout's role)
  • Chase dependency chains beyond 3 hops for the explanation (deeper analysis belongs in $map)