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:

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:

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.