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. 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. Ask the local model for JSON that matches docs/kb/request-analysis-schema.json.
6. Validate the JSON.
7. 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:

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
- write a short descriptive title
- explain the user intent in plain language
- propose a likely implementation path
- 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:

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.