playbooks

home / skills / bdambrosio / cognitive_workbench / map

map skill

/src/primitives/map

This skill applies a specified operation to every item in a collection, returning a new collection of results with nulls filtered.

npx playbooks add skill bdambrosio/cognitive_workbench --skill map

Review the files below or copy the command above to add this skill to your agents.

Files (1)
Skill.md
1.7 KB
---
name: map
type: primitive
description: Apply operation to each item in Collection
---

# Map

## INPUT CONTRACT

- `target`: Collection (variable or ID)
- `operation`: Tool/primitive name (string) or dict with `tool` field
- `out`: Variable name
- Additional fields: Tool-specific parameters

**REQUIREMENTS:**
- `target` MUST be Collection
- `operation` MUST be valid tool/primitive name
- Operation applied to each Note in Collection

**NOT SUPPORTED IN MAP:**
- Collection-only primitives: `size`, `union`, `intersection`, `difference`, `join`, `filter-structured`, `sort`, `head`, `flatten`, `split`
- Control flow: `if`, `while`, `wait`
- Discovery/search primitives: `discover-notes`, `discover-collections`, `search-within-collection`
- Persistence: `persist`, `load`, `index`

## OUTPUT

Returns Collection of Notes, each containing result from applying operation. Failed/null results excluded if `filter_null=true` (default).

## FAILURE SEMANTICS

**Empty Collection = expected when:**
- All operations fail or return null
- Type contract violated

**Empty ≠ error** — indicates no successful results, not failure.

**Actual failures:** Invalid target type, unknown operation, or missing parameters.

## REPRESENTATION INVARIANTS

- `map(load)` on search-web results returns empty (results already materialized Notes)
- Empty result from `map(load)` = expected behavior, not diagnostic

## ANTI-PATTERNS

❌ `map(target=$note, operation="refine")` → Must be Collection
❌ `map(target=$results, operation="load")` → search-web results already Notes
❌ `map(target=$coll, operation="split")` → `split` operates on Notes, not Collections
❌ Treating empty result as error → Empty = no successful operations

Overview

This skill applies a specified operation to every Note inside a Collection and returns a Collection of the results. It enforces type contracts so the input target must be a Collection and the operation must be a valid tool or primitive. The returned Collection contains only successful, non-null results by default.

How this skill works

You supply a Collection as target and an operation name or operation descriptor. The skill runs the operation once per Note in the Collection and assembles Notes containing each operation result. By default it filters out null or failed results unless configured otherwise. Some primitives and control-flow or discovery tools are intentionally unsupported because they operate on Collections or external state.

When to use it

  • Apply a transformation or analysis to every Note in a Collection (e.g., annotate, summarize, translate).
  • Batch-run a Note-level primitive across a set of notes and collect successful outputs.
  • Materialize per-note results into a new Collection for downstream processing.
  • Filter out failed or null outputs while preserving successful operation results.
  • Avoid when the operation expects a Collection or when running discovery/persistence primitives.

Best practices

  • Always provide a Collection for target; single Note or other types will violate the contract.
  • Choose Note-level primitives (tool/primitive) rather than Collection-only primitives.
  • Set explicit parameters required by the chosen operation; missing params cause failures.
  • Treat an empty returned Collection as expected: it means no successful results, not an error.
  • Avoid using operations like load on already-materialized search results because they return empty by design.

Example use cases

  • map a summarization primitive across a Collection to produce a Collection of summaries.
  • Apply a language-detection tool to each Note to tag notes by language.
  • Run a redaction or PII-scrubbing operation on every Note and gather cleaned results.
  • Convert each Note's content format (e.g., HTML→markdown) and collect converted Notes.
  • Execute a validation primitive to filter out invalid notes while keeping valid ones.

FAQ

What happens if the target Collection is empty or every operation fails?

The skill returns an empty Collection. That outcome is expected and indicates no successful results, not an error.

Can I pass a primitive that operates on Collections?

No. Collection-only primitives (size, union, sort, filter-structured, split, etc.) are not supported in map because map applies operations per Note.