# Request Queue Workflow

This document describes a practical first pass for automated request analysis using the KB scaffold.

## Goal

Turn raw launcher submissions into structured request items that are:

- titled
- categorized
- tagged
- explained in plain language
- paired with a realistic implementation approach

## Recommended Pipeline

1. Read one pending submission.
2. Split it into candidate atomic requests.
3. Retrieve likely systems from `docs/kb/systems.json`.
4. Load the matching `docs/kb/systems/*.md` files.
5. Load the standardized request tags from `docs/kb/tags.json`.
6. Ask the local model for JSON that matches `docs/kb/request-analysis-schema.json`.
7. Validate the JSON.
8. Promote high-confidence items and hold low-confidence items for review.

## Suggested Confidence Rules

- `>= 0.85`
  - auto-promote to active
- `0.65 - 0.84`
  - store as needs review
- `< 0.65`
  - keep as pending or send to manual triage

## Retrieval Hints

Search `systems.json` using:

- request text
- obvious UI words like "layer", "chunk", "overview", "graphics", "animation"
- aliases
- past tags from similar requests

If a submission touches multiple subsystems, feed the model the top two to four matching docs instead of the whole KB.

## Prompt Skeleton

Use a strict instruction similar to this:

```text
You are processing Worldshaper editor requests.

You must:
- split the submission into one or more atomic requests
- assign one primary category per item
- assign tags grounded in the provided KB and limited to `docs/kb/tags.json`
- write a short descriptive title
- explain the user intent in plain language
- propose a likely implementation path
- provide a short review rationale and possible options when confidence is low
- avoid inventing systems that are not in the KB
- return only valid JSON matching the provided schema

If you are unsure, lower confidence and use statusRecommendation = "needs_review".
```

Then provide:

- the raw submission
- the JSON schema
- the retrieved KB docs

## Good First Storage Shape

Keep the existing launcher request record, but add optional analysis metadata:

- `analysisStatus`
- `analysisConfidence`
- `analysisModel`
- `analysisCreatedAt`
- `analysisUpdatedAt`
- `analysisPayload`

This lets you keep the current user-facing `pending` and `active` states while adding a back-office workflow.

## First Implementation Target

The simplest useful worker would:

1. read pending requests from the launcher request API/store
2. analyze one request at a time
3. write structured analysis back to the same store
4. never delete the original `sourceText`

The current first-pass implementation is:

```bash
npm run analyze:requests
```

Useful environment variables:

- `REQUEST_ANALYZER_API_BASE`
- `REQUEST_ANALYZER_PROVIDER`
- `REQUEST_ANALYZER_MODEL_BASE_URL`
- `REQUEST_ANALYZER_MODEL`
- `REQUEST_ANALYZER_API_KEY`
- `REQUEST_ANALYZER_MAX_TOKENS`
- `REQUEST_ANALYZER_THINKING`
- `REQUEST_ANALYZER_PROMOTE_THRESHOLD`
- `DEEPSEEK_API_KEY`

DeepSeek path:

- set `DEEPSEEK_API_KEY`
- leave the provider on its default auto-detect setting
- the worker will use DeepSeek-hosted chat completions automatically

Behavior:

- high-confidence all-active results replace the pending submission with active request rows
- mixed or lower-confidence results stay on the pending submission as review metadata
- failures are stored as analysis errors instead of silently disappearing

## What Not To Automate First

- automatic deletion
- automatic deduplication with destructive merges
- direct code generation
- automatic schema migrations

The first win is dependable triage, not full autonomy.