Imported from provenmap/pmap-claude (plugins/architect/claude/pmap-architect/knowledge/discover-authoring/SKILL.md). Install upstream with npx skills add provenmap/pmap-claude --skill discover-authoring. Copyright stays with the author.

Discover — authoring the answers a graph can give

/discover is graph-first and fast. A script reads the context pack, scores what the architecture can answer on its own, and offers two ranked menus: insights (an observation about one element from its own characteristics, traced as a trail) and context boards (why something matters, drawn as a small board of its relationships). The user picks, or asks the script to choose. Agents author the picks in parallel from a brief; a script pushes them in order; a report closes.

The same skill serves the ProvenMap Code, Connect and Architect plugins. Only the universe differs: the bound board's tree for code and connect, the whole workspace for the architect.

The two answer shapes

The wow levers (the script enforces them; the agent keeps them)

• The trail is the demo. Every insight ships a multi-stop trail; a fan-out from a hub (branch stops sharing one from) reads instantly; a layer hop makes the camera fly.
• Half the insights cross a layer when the tree has one — and every crossing means something: a chokepoint or cascade descends into the dependent onto the code that makes the call, a journey climbs back through a boundary port onto the owner and across the parent edge, a hand-off names the one element inside a drill-down that talks to its siblings. The script proves each hop the way the server does (references/families.md, "Layer crossings"); on the landscape, a flow across apps.
• Variety in the set — distinct polarities across the insights, no two items on one anchor, every level the universe has, at most one ghost proposal.
• C4-shaped context boards — the level in the reading strip; the subject the one xl; the first ring lg so its notes read on the canvas; people and externals small; the answer's path the heavy edges, each with its flow kind; kind left to the archetype. The script decides all of it (references/c4-reading.md); the push applies it.

What a brief is

--briefs writes one JSON per chosen candidate: the candidate itself (trail or drawn board, ready to copy), the slice of the pack around it (its elements plus one hop, with their edges and boards), the archetype families it needs, the org's context-tag names, the single output path to write, and the rules path — references/authoring.md, the agent-facing contract. The layout keeps preparation and results apart: discover/ holds only the plan, the briefs, the context packs and the ledger; an insight's output lands in insights/<id>.json and a context board's in context-maps/<id>.json (under .provenmap/ for the code and connect plugins, under the working set for the architect). verify says what the agent may read beyond the brief: source (code plugin: files named in element descriptions, to confirm a number) or pack (connect, architect: nothing else).

Rules that never bend

1. Copy, never invent. The trail's stops, via.edge slugs, board and node slugs, and a drawn board's nodes, edges and sources come from the candidate verbatim. An agent adds prose and notes; it never adds a stop, a node, an edge, or a slug. The save gates reject anything else, and a board that shows what the architecture lacks is worse than no board.
2. One file per brief, at output. Nothing else on disk. The reply is one line.
3. No network. The pack is the evidence; for code, source files confirm a number.
4. Push in order, from the orchestrator. Agents author; the CLI pushes — one paced writer, never four. A failed push is fixed once from validationErrors, else marked failed and the run continues.
5. Re-runs replace. The previous run's context boards are removed before this run's first push; insights replace through the skill's replace mode. A board edited since we drew it is kept and named.

References

• references/authoring.md — the agent contract: how to author one brief into an insight push or a context-board payload
• references/families.md — every candidate family: the question it answers, the shape it draws, the prose that fits it
• references/context-board-payload.md — the context-board payload schema and its gates
• references/c4-reading.md — how a drawn board reads as a C4 diagram: what each instrument asserts, and the note style per level
• references/discover-workflow.md — the command's Steps 2–7, clause by clause
• ../insights/references/report-output-format.md — InsightDraft, Trail, Stop, Proposal (shared with /insights)