132 lines
3.6 KiB
Markdown
132 lines
3.6 KiB
Markdown
# 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.
|