# Source-Grounded Semantic Explainer

## Decision

The short-term product feature for the AI Capability Playbook is a source-grounded semantic explainer over the approved playbook and context package.

```text
We are not building a chatbot.
We are building a governed interpretation layer over an approved AI capability knowledge package.
```

The data/context layer is the product. The model is the interpreter.

The value is not a smarter model by itself. The value is a governed, source-bounded, well-structured knowledge package that a model can interrogate without drifting outside the approved package boundary.

## Product Role

The explainer should help readers locate, understand, and apply the playbook without turning the playbook into an open-ended agent runtime.

It should operate over approved package structure first:

```text
approved source package
  -> artifact manifest
  -> section ids
  -> source paths
  -> canonical titles
  -> audience/type tags
  -> claim/source boundaries
  -> compact context pack
  -> citation map
```

The MVP should not start with a database, graph, vector store, hosted retrieval service, embedding-provider upgrade, connector ingestion, durable memory, or provider execution path. Those remain deferred until the package, context pack, manifest, source map, and section index prove insufficient.

## MVP Modes

### Find

Use Find when a user asks where the playbook covers a topic.

Expected behavior:

- return matching artifacts and sections
- provide a compact explanation of why the matches matter
- cite source paths, section IDs, artifact IDs, or context-pack references where available
- identify related sections when the package structure supports it
- return a clear not-found response when the approved package is silent

Minimum response shape:

| Field | Requirement |
|---|---|
| Query restatement | Restate the user topic in neutral terms. |
| Matching sections | List artifact title, artifact ID, section title, section ID, and source path where available. |
| Why it matters | Explain the relevance in one or two plain-language sentences. |
| Related package areas | Include adjacent sections only when supported by package metadata or explicit source content. |
| Not-found behavior | Use the refusal pattern when no approved package support is found. |

### Explain

Use Explain when a user asks what a playbook concept means or how two concepts differ.

Expected behavior:

- answer in plain language
- cite approved package sources only
- preserve field-guidance-not-policy posture
- distinguish guidance from approval
- avoid answering from model memory when the package is silent

Minimum response shape:

| Field | Requirement |
|---|---|
| Direct explanation | Explain the concept without making it sound like final policy. |
| Source basis | Cite source path, artifact ID, section ID, or context-pack reference. |
| Boundary | State what the explanation does not approve when approval meaning could be confused. |
| Package silence | If unsupported, state that the approved package does not cover the answer. |

### Assess

Use Assess when a user supplies a proposed AI use case, architecture submission, assistant concept, workflow, or capability proposal.

Expected behavior:

- evaluate the submission against AICD criteria
- map each finding to playbook criteria and source sections
- classify observations as `pass`, `concern`, `blocker`, `missing evidence`, or `not covered`
- produce review-ready derivative outputs where appropriate

Assessment details are defined in [PROPOSAL_ASSESSMENT_PATH.md](PROPOSAL_ASSESSMENT_PATH.md).

## Citation Contract

Every grounded answer should cite the strongest available package reference:

1. artifact ID and title
2. section ID and section title
3. source path
4. context-pack path or source-map reference
5. claim ID or source boundary when the answer depends on claim posture

If the citation is missing from the package structure, the explainer should state that limitation instead of inventing a citation.

## Refusal Patterns

Use these patterns as explicit product behavior:

```text
Not found in the approved playbook package.
```

```text
The playbook provides guidance, but it does not approve this tool, data class, workflow, production use, or company policy.
```

```text
The submitted proposal lacks enough evidence to assess this criterion.
```

Refusal is a feature. It preserves source boundary, approval meaning, and trust in the package.

## Non-Goals

This note does not implement:

- runtime chatbot behavior
- backend or database behavior
- vector store retrieval
- hosted retrieval service
- provider/model execution
- connector ingestion
- enterprise workflow integration
- durable memory
- generated assessment output as source truth

## Relationship To Existing Issues

| Issue | Relationship |
|---|---|
| #150 | This note builds on the product architecture decision that the playbook is the active governed knowledge package. |
| #78 | This note advances #78 by making the source-grounded assistant path product-specific and package-bound. |
| #79 | Backend and graph evaluation remains deferred until flat package structure proves insufficient. |
| #88 | Reader orientation should still land before broad assistant implementation if users need clearer package entry paths. This note can inform that orientation. |
| #151 | DOCX rebuild idempotence remains separate and is not superseded. |