# Governance and design notes

## Purpose

The Support Knowledge Assistant demonstrates a reviewable pattern for retrieving support guidance and routing higher-risk questions. It is a public portfolio prototype using a fictional SaaS product and synthetic content.

The goal is not to automate every answer. The goal is to make useful, bounded assistance possible while preserving evidence and human ownership.

## Current decision boundary

The browser applies two separate checks:

1. Retrieval ranks the included articles and calculates visible evidence signals.
2. Policy rules decide whether the result may be shown as a cited answer or must be presented as a human-review path.

A strong content match does not override a policy signal. A security concern can retrieve the correct security article and still require a person.

## Required human review

The implemented rules require review for:

- Security concerns, including suspected compromise, phishing, suspicious access, and exposed credentials
- Broad service impact, including system-wide failures, failed writes, missing records, and possible data loss
- Sensitive information, including personal, regulated, confidential, and payment data
- Low-confidence questions that are weakly supported or outside the knowledge base

The prototype returns safe intake guidance when an applicable article exists. It never treats that guidance as authorization to investigate, change access, expose data, or close an incident.

## Evidence shown to the user

Each result displays:

- Disposition: cited answer or human review
- Article ID, title, section, and updated date
- Matched terms and retrieval score
- Confidence label and numeric heuristic
- Policy reasons that triggered review
- A link to the complete synthetic source article

This evidence is intentionally visible in the normal interface, not hidden in developer logs.

## Confidence limits

Confidence combines the top retrieval score, query-term coverage, and the score margin between the first and second results. The threshold is currently 0.50.

This value is a routing heuristic. It is not a calibrated probability, and 80% confidence does not mean an answer has an 80% chance of being correct. A production threshold would require representative test data, error-cost analysis, and periodic recalibration.

## Data handling

- All included content is synthetic.
- The browser does not send questions to a server.
- The project uses no analytics, cookies, model API, or external data store.
- Refreshing or closing the page clears the entered question.
- The interface warns users not to enter credentials, personal data, or customer information.

GitHub Pages may produce standard hosting logs outside this application's control. A real deployment would require a reviewed privacy notice, defined retention, access logging, and an approved data flow.

## Content lifecycle for a real system

A production knowledge workflow would need:

1. Named article owners and reviewers
2. Approval state and effective dates
3. Role-based access for restricted guidance
4. Scheduled review and expiration rules
5. Change history with rollback
6. Feedback intake connected to source revisions
7. Incident procedures for incorrect or unsafe content

## Evaluation and change control

The committed evaluation set provides a repeatable regression check. Retrieval logic, policy signals, or article changes should be reviewed with the changed results before release.

The current test set is small and purpose-built. A real pilot would add paraphrases from representative users, ambiguous questions, multilingual cases, adversarial prompts, content conflicts, stale articles, access-controlled content, and measured business outcomes.

## Production requirements not implemented

- Authentication and role-based authorization
- Source-level access filtering
- Service desk or enterprise application integration
- Audit events and centralized monitoring
- Content-management approval workflow
- Privacy, legal, and security assessment
- Abuse controls and prompt-injection testing
- Operational ownership and response procedures
- Reliability objectives, backup, and recovery
- Representative offline evaluation and controlled user acceptance testing

These are documented as future requirements, not implied capabilities.