Cause: The requirements tools expect Claude to output strict JSON only. Occasionally the model adds explanatory text, markdown headers, or partial responses when the PRD is very large or ambiguous.

Fix:

• The system already strips ```json code fences automatically — this catches ~95% of cases.
• If it still fails, retry the failed step individually (the buttons run a single step at a time).
• Check the server console for the raw LLM output (first 500 chars are logged in the error).
• If your PRD is very large, the system truncates at 80,000 characters. Try splitting into focused sections.

Cause: The FAISS index is empty, or the retrieval query does not match any stored chunks with similarity ≤ 1.5 (L2 distance threshold).

Fix:

• Check Memory Status in the sidebar — "Chunks" should be > 0.
• If chunks = 0, ingest your documents first via the Ingest panel or POST /ingest.
• Try rephrasing the question using vocabulary from the document (e.g. exact section names, technical terms).
• If the FAISS index files (data/faiss_index.index, data/faiss_index.meta) were deleted, re-ingest all documents.

Cause: The filepath provided doesn't match the actual file on disk.

Common mistakes:

• Using absolute paths: /data/my-doc.pdf → use data/my-doc.pdf (leading / is auto-stripped, but check casing).
• Spaces in folder names: "data/VIC-PTG_Files" vs "data/VIC -PTG_Files" — preserve exact spacing.
• Wrong extension: .PDF vs .pdf (Linux is case-sensitive).

Cause: You attempted to run ② Generate SYS Reqs or ③ Generate SWR Reqs without first running ① Extract STK Needs, or the extraction step failed silently.

Fix:

• Always run the pipeline in order: STK → SYS → SWR. The "Run Full Pipeline" button enforces this automatically.
• If running individually, confirm the STK step showed a success count before proceeding.
• Check GET /requirements/list?level=stakeholder returns entries before proceeding.

Cause: FAISS index files (data/faiss_index.index and data/faiss_index.meta) are absent — either first run or accidentally deleted.

Fix:

• The system will create a new empty index automatically on startup — no action needed to fix the error itself.
• Re-ingest all your documents to rebuild the index. The files will be persisted on the next document add.

Cause: file_write enforces a security boundary — writes are only allowed inside data/.

Fix: Change your filepath to start with data/, e.g. data/summary.txt instead of results/summary.txt.

DOCX fails entirely:

• Verify python-docx is installed: pip install python-docx.
• Check the server console for a Python traceback.

Excel fails entirely:

• Verify openpyxl is installed: pip install openpyxl.

Export succeeds but tables are empty:

• No requirements exist at that level yet — run the pipeline first.
• For SyRS: must have SYS reqs. For SRS: must have SWR reqs.

Cause: This is expected behaviour. Each pipeline step (STK, SYS, SWR) makes a full Claude API call with the entire PRD or existing requirements as context.

• STK extraction: sends the full PRD text (up to 80k chars) to Claude.
• SYS generation: sends all STK requirements as JSON to Claude.
• SWR generation: sends all SYS requirements as JSON to Claude.

For a 50-page PRD generating 15 STK → 40 SYS → 80 SWR, total time is typically 2–4 minutes.

Cause: The request body is missing a required field or the type is wrong (e.g. sending a number where a string is expected).

Fix:

• Visit http://localhost:8000/docs — Swagger UI shows the exact schema for every endpoint.
• Check the 422 response body: it contains a detail array identifying exactly which field failed and why.

Cause: An unhandled exception in a tool or the orchestrator. Common causes:

• Missing Python dependency (pypdf, python-docx, openpyxl, sentence-transformers).
• Corrupted data/requirements/requirements.json — delete the file and re-run the pipeline.
• Corrupted FAISS index — delete data/faiss_index.* and re-ingest documents.
• Expired or invalid ANTHROPIC_API_KEY in .env.

Fix: Check the server console (uvicorn output) for the full Python traceback.

Cause: The ID passed to GET /requirements/{req_id} or PATCH /requirements/{req_id} does not exist in the store.

Fix: Use GET /requirements/list to retrieve all valid IDs first, or browse the Requirements tab list.

Use the exact requirement name, signal name, or ID from the document. Prometheus will retrieve the closest matching chunks.

State the observed symptom in positive, technical terms. Avoid negations ("not working", "not triggered") — phrase what you are trying to find, not what is absent.

State both subjects explicitly with the attribute you want compared.

Name the document or version when multiple sources have been ingested. This guides retrieval to the right chunks.

Scope your list request to a specific feature area or document section. Broad list requests retrieve chunks that may span unrelated topics.

The extraction prompt instructs Claude to reference PRD sections in the source field. Numbered headings (1.1, 2.3.4…) or named sections like "User Interface Requirements" give cleaner traceability than unstructured prose.

Each pipeline step appends to the store — it does not overwrite. If you run STK extraction twice, you get two sets with non-overlapping IDs (e.g. STK-001…STK-012, then STK-013…STK-020). To start fresh, delete data/requirements/requirements.json before running.

When a SYS requirement lists derived_from: ["STK-001"], the store automatically appends the SYS ID to STK-001.allocated_to. You never need to manually maintain both directions of the link.