# Manage Discoveries

> Reviews, approves, and rejects existing discoveries. Use for the approval queue, discovery states, or user feedback on a discovery.

- Skill: `altertable-ai/manage-discoveries` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add altertable-ai/manage-discoveries`
- Raw SKILL.md: https://api.skillmd.com/api/skills/altertable-ai/manage-discoveries/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: altertable-ai (https://skillmd.com/u/altertable-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/altertable-ai/manage-discoveries

---


# Manage Discoveries

## Quick Start

To manage discoveries:

1. Call `initialize` before inspecting organization data
2. Find discovery entities with `search_entities` and read the selected entity resource for details
3. Assess factual accuracy, novelty, actionability, and timing
4. Recommend approve/reject, or perform the review in the Altertable app if your harness exposes that action
5. When feedback arrives, extract the user's intent and act on it

## Finding Discoveries

Use the MCP entity tools to retrieve discoveries:

- `search_entities` with discovery-related query terms or `node_types` when available
- `altertable://ontology/entities/{slug}` to read the full entity content after finding a slug
- `take_screenshot` when you need to verify how the discovery renders

Available statuses for filtering: `pending`, `approved`, `rejected`.

The public MCP tool surface may not expose an approval mutation. If no review tool is available in your harness, provide a clear recommendation and direct the user to review the discovery in Altertable.

## Reviewing a Discovery

When you need to review a discovery, follow these steps in order:

1. **Check factual accuracy** -- Does the title match the underlying data? Are the numbers correct?
2. **Verify it is not a duplicate** -- Search existing discoveries for overlapping findings before approving.
3. **Assess actionability** -- Can the reader do something with this information? If not, reject.
4. **Evaluate timing** -- Is this finding still current, or has the data gone stale?
5. **Decide**: approve if steps 1-4 all pass; reject if the analysis is wrong, duplicated, stale, or not actionable.

For batch reviews, sort by priority first, then group by topic, and apply the same five-step check to each.

## Discovery Lifecycle

Discoveries flow through these states:

```
pending  -->  approved | rejected
```

| State      | Description             | Transitions                    |
| ---------- | ----------------------- | ------------------------------ |
| `pending`  | Awaiting review         | approve → approved; reject → rejected |
| `approved` | Approved                | reject → rejected              |
| `rejected` | Rejected                | approve → approved             |

Both `approve` and `reject` are reversible: an approved discovery can later be rejected, and a rejected one can later be approved.

## Processing User Feedback

Feedback on a discovery has two fields: a **reaction** (`approved` or `rejected`) and an optional **reason** (free-text, max 1000 chars).

When processing feedback:

1. **Note the reaction** -- approved or rejected.
2. **Parse the reason text** -- free-text comments often contain the actionable signal.
3. **Detect implicit preferences** -- does the feedback signal a topic the user cares more or less about?
4. **Take action** immediately on anything concrete in the reason.

When feedback includes free-text comments, parse them for:

- Direct requests ("show me this by region")
- Threshold adjustments ("only alert me if the change is over 10%")
- Topic preferences ("I don't care about this metric")
- Accuracy challenges ("the number is wrong because...")

## Common Pitfalls

- **Approving without checking for duplicates.** Always search existing discoveries before approving a new one.
- **Ignoring the free-text reason.** The `approved`/`rejected` reaction alone carries little information; the reason text is where the actionable signal usually lives.
- **Over-alerting.** If a user has rejected several discoveries on the same topic, stop surfacing similar findings until new data changes the picture.

## Reference Files

- [Review patterns](references/review-patterns.md) - Read when batch-reviewing multiple discoveries or designing a review strategy
- [Intent detection](references/intent-detection.md) - Read when processing free-text feedback to extract actionable instructions