Worldshaper/docs/kb/queue-workflow.md

# 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. Run a light routing pass that maps slang and broad language onto likely systems and tags.
3. Retrieve likely systems from `docs/kb/systems.json`.
4. Retrieve likely focused modules from `docs/kb/modules.json`.
5. Load only the matching `docs/kb/systems/*.md` and `docs/kb/modules/*.md` files.
6. Load the standardized request tags from `docs/kb/tags.json`.
7. Ask the local model for JSON that matches `docs/kb/request-analysis-schema.json`.
8. Validate the JSON.
9. 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 system docs plus the smallest helpful focused modules instead of the whole KB.

Use `terminology.json` during the routing pass so phrases like "sprite editor", "painting tool", "recoloring", and "engine" still resolve to the intended Worldshaper concepts.

## 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 routing summary
- 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
- broad or ambiguous requests should still receive a useful interpretation, likely systems, and possible directions instead of a dead-end review

## 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.