# Decision Store

> Record, query, and conflict-check architectural and design decisions across the OmniNode platform

- Skill: `omninode-ai/decision-store` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add omninode-ai/decision-store`
- Raw SKILL.md: https://api.skillmd.com/api/skills/omninode-ai/decision-store/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: OmniNode-ai (https://skillmd.com/u/omninode-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/omninode-ai/decision-store

---


# decision-store skill

**Skill ID**: `onex:decision_store`
**Version**: 1.1.0
**Owner**: omniclaude
---

## Purpose

Record, query, and conflict-check architectural and design decisions across the OmniNode
platform. Decisions are persisted by `NodeDecisionStoreEffect` and queried
via `NodeDecisionStoreQueryCompute`.

Conflicts are detected in two stages:
1. **Structural check** (sync, pure function) — always runs
2. **Semantic check** (async, LLM via DeepSeek-R1) — only if structural confidence >= 0.6

HIGH-severity conflicts trigger the Slack conflict resolution gate, which blocks
the pipeline until an operator resolves each conflict via Slack reply.

---

## Sub-operations

### `record`

Write a new decision entry, run structural conflict check against all existing entries
in the same domain, and route to Slack if any conflict is HIGH severity.

```
/decision-store record
  --type TECH_STACK_CHOICE|DESIGN_PATTERN|API_CONTRACT|SCOPE_BOUNDARY|REQUIREMENT_CHOICE
  --domain <domain>
  --layer architecture|design|planning
  --services <svc1,svc2,...>   # omit = platform-wide
  --summary "<one-line summary>"
  --rationale "<full rationale>"
  [--dry-run]
```

Behavior:
1. Validate required fields.
2. Call `NodeDecisionStoreEffect` to persist the entry.
3. Run `structural_confidence()` against all existing entries in the same domain.
4. For each conflict with confidence > 0.0, call `compute_severity()`.
5. If any severity is HIGH: post Slack conflict notification (via `_lib/slack-gate` helpers)
   and wait for operator resolution via Slack command grammar.
6. If structural confidence >= 0.6: fire async `semantic_check_async()` — non-blocking.
7. Emit `decision-conflict-status-changed.v1` event for each new conflict (status = OPEN).
8. Emit `decision-conflict-status-changed.v1` on each subsequent status transition
   (OPEN -> RESOLVED or OPEN -> DISMISSED) after Slack resolution.

### `query`

Retrieve existing decisions with optional filters and cursor-based pagination.

```
/decision-store query
  [--domain <domain>]
  [--layer architecture|design|planning]
  [--type <decision_type>]
  [--service <service_name>]
  [--status open|resolved|dismissed]
  [--cursor <cursor_token>]
  [--limit 20]
```

Behavior:
1. Call `NodeDecisionStoreQueryCompute` with filter params.
2. Display paginated results with conflict indicators.
3. If `--cursor` provided, fetch next page.

### `check-conflicts`

Dry-run structural conflict check for a hypothetical new decision, without writing anything.

```
/decision-store check-conflicts
  --type <decision_type>
  --domain <domain>
  --layer architecture|design|planning
  --services <svc1,svc2,...>
  --summary "<one-line summary>"
```

Behavior:
1. Run `structural_confidence()` and `compute_severity()` against all existing entries.
2. Display conflict report: confidence scores, severities, affected entries.
3. Does NOT write to the store. Does NOT trigger semantic check. Does NOT emit events.

---

## Severity Matrix

| Decision Type | Layer | Base Severity |
|---|---|---|
| TECH_STACK_CHOICE | architecture | HIGH |
| TECH_STACK_CHOICE | design | HIGH |
| TECH_STACK_CHOICE | planning | MEDIUM |
| DESIGN_PATTERN | architecture | HIGH |
| DESIGN_PATTERN | design | MEDIUM |
| DESIGN_PATTERN | planning | LOW |
| API_CONTRACT | architecture | HIGH |
| API_CONTRACT | design | MEDIUM |
| API_CONTRACT | planning | LOW |
| SCOPE_BOUNDARY | architecture | MEDIUM |
| SCOPE_BOUNDARY | design | MEDIUM |
| SCOPE_BOUNDARY | planning | LOW |
| REQUIREMENT_CHOICE | architecture | MEDIUM |
| REQUIREMENT_CHOICE | design | LOW |
| REQUIREMENT_CHOICE | planning | LOW |

**Modifiers (applied in order after base):**

1. **Platform-wide scope** (either entry has `scope_services = []`): floor at MEDIUM
2. **Architecture layer** (either entry has `scope_layer = "architecture"`): floor at HIGH
3. **Semantic shift** (from DeepSeek-R1): +/-1 step, clamped to [LOW, HIGH]

**Hard rules:**
- `structural_confidence == 0.0` (cross-domain): no conflict, semantic check MUST NOT run
- `structural_confidence == 0.3` (disjoint services): semantic check CANNOT escalate to HIGH
- Semantic check only runs if `structural_confidence >= 0.6`

---

## Structural Confidence Values

| Value | Meaning |
|---|---|
| 0.0 | Cross-domain — no possible conflict (semantic blocked) |
| 0.3 | Disjoint service sets — low probability (semantic capped at MEDIUM) |
| 0.4 | Same domain, different layer |
| 0.7 | Overlapping service sets |
| 0.8 | One platform-wide vs specific |
| 0.9 | Both platform-wide |
| 1.0 | Identical service scope |

---

## Conflict Resolution (Slack Notification)

When a HIGH severity conflict is detected after `record`, the pipeline posts a conflict
notification to Slack (via `_lib/slack-gate` credential helpers) and blocks until an
operator resolves the conflict via the command grammar below.

### Slack Command Grammar

Operators resolve conflicts by replying in the Slack gate thread:

```
Format:  <action> <conflict_id> [note]

Actions:
  proceed <id> [note]  — mark RESOLVED, record approver + note, continue pipeline
  hold    <id>         — pipeline stays paused (gate remains open)
  dismiss <id>         — mark DISMISSED permanently (no further checks for this pair)
```

**`proceed` rules:**
- `proceed <id>` with no note -> `resolution_note = "proceed (no note provided)"`
- `proceed <id> <note>` -> `resolution_note = <note text>`

**`hold` rules:**
- Pipeline stays paused; no state change; no event emitted

**`dismiss` rules:**
- Conflict marked DISMISSED permanently
- This decision pair will NEVER trigger a Slack gate again (even if re-recorded)
- `resolution_note` is `None` for dismissals

**Multiple conflicts:**
- Each conflict must be resolved separately in its own reply
- All OPEN conflicts must be resolved before the pipeline resumes
- RESOLVED and DISMISSED conflicts do not block the pipeline

**Unrecognized commands:**
- Re-prompt operator with usage text; no state changes

### Conflict Workflow (Full Sequence)

```
1. record sub-operation detects HIGH conflict
2. Post conflict notification to Slack (via _lib/slack-gate helpers)
3. Pipeline blocks (polling for Slack replies)
4. Operator replies with: proceed | hold | dismiss
5. For proceed:
   - Update conflict: status=RESOLVED, resolved_by, resolved_at, resolution_note
   - Emit decision-conflict-status-changed.v1 (OPEN -> RESOLVED)
   - If all conflicts resolved: resume pipeline
6. For hold:
   - No state change, no event
   - Continue polling
7. For dismiss:
   - Update conflict: status=DISMISSED
   - Emit decision-conflict-status-changed.v1 (OPEN -> DISMISSED)
   - Mark pair as permanently suppressed
   - If all conflicts resolved/dismissed: resume pipeline
8. Pipeline resumes after all blocking conflicts are RESOLVED or DISMISSED
```

---

## Status Change Events

`decision-conflict-status-changed.v1` is emitted on EVERY conflict status transition.

**Topic constant**: `TopicBase.DECISION_CONFLICT_STATUS_CHANGED`
**Wire topic**: `onex.evt.omniclaude.decision-conflict-status-changed.v1`
**Source**: `omniclaude/src/omniclaude/hooks/topics.py`

**Transitions that emit:**
- `None -> OPEN` (conflict first detected during `record`)
- `OPEN -> RESOLVED` (via `proceed` command)
- `OPEN -> DISMISSED` (via `dismiss` command)

**Payload:**
```json
{
  "conflict_id": "uuid",
  "old_status": "OPEN | null",
  "new_status": "OPEN | RESOLVED | DISMISSED",
  "resolved_by": "slack_user_id | null",
  "resolved_at": "ISO8601 | null",
  "resolution_note": "string | null"
}
```

Note: `old_status` is `null` for the initial OPEN event (no previous status).
`resolution_note` is `null` for `dismiss` actions.

---

## Files

| File | Purpose |
|---|---|
| `SKILL.md` | This document — usage, severity matrix, conflict resolution workflow |
| `prompt.md` | Operational prompt followed by the agent |
| `detect_conflicts.py` | `structural_confidence()` and `compute_severity()` pure functions |
| `semantic_check.py` | Async LLM check via DeepSeek-R1 (only if structural >= 0.6) |
| `examples/record_decision.md` | Example: recording a tech stack choice |
| `examples/query_decisions.md` | Example: querying decisions with filters |
| `examples/conflict_resolution.md` | Example: Slack conflict resolution walkthrough |

---

## Dependencies

| Component | Role |
|---|---|
| `ModelDecisionStoreEntry`, `ModelDecisionConflict` | Data models |
| `NodeDecisionStoreEffect` | Write node |
| `NodeDecisionStoreQueryCompute` | Query node |
| `TopicBase.DECISION_CONFLICT_STATUS_CHANGED` in `topics.py` | Event emission |
| Slack command grammar + status change events | Conflict gate |

---

## Event Schema

**`decision-conflict-status-changed.v1`** (emitted on every status transition):

```json
{
  "conflict_id": "uuid",
  "old_status": "OPEN | RESOLVED | DISMISSED | null",
  "new_status": "OPEN | RESOLVED | DISMISSED",
  "resolved_by": "string | null",
  "resolved_at": "ISO8601 | null",
  "resolution_note": "string | null"
}
```

**Note**: The event schema was simplified in an earlier pass. Fields `decision_a_id`,
`decision_b_id`, and `approver` were consolidated: `approver` is now `resolved_by`,
and decision pair IDs are carried by the conflict record (not the status event).
The status event is intentionally minimal — consumers query the conflict record for
full decision pair context.