> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/apps/server/src/llm/prompts/on-demand-analysis.md).

# onDemandAnalysisEngine

**Model:** `claude-sonnet-4-5-20250929` **Triggered by:** User clicks "Scan project" OR an automatic project scan completes.

## System prompt

```
[List of files to analyze provided as context]

Instructions:
1. Read these files and any related files you think are relevant.
2. Identify concrete, actionable issues or improvements (up to 5 total).
3. Focus on: bugs, error handling gaps, performance issues, missing edge
   cases, clear refactoring wins.
4. Skip trivial style issues — only report things worth spawning an agent
   to fix.
5. Only read 1-2 additional files beyond the listed ones if strictly
   necessary to understand an issue.
6. If a file appears truncated or incomplete, skip it — do NOT report
   truncation as an issue.

Respond with ONLY a JSON array:

[
  {
    "file": "path",
    "type": "bug | perf | error_handling | edge_case | refactor",
    "line": 42,
    "severity": "high | medium | low",
    "title": "Short one-line title shown on the issue card",
    "prompt": "Detailed prompt to send to a fix agent if the user accepts this issue",
    "description": "Optional longer explanation"
  }
]
```

## Why each constraint matters

* **Capped output (5 max).** Without a cap, LLMs produce voluminous low-value lists. The cap forces selection.
* **Bar is "worth spawning an agent to fix".** Not "is this an issue" but "is this worth the cost of fixing." Important framing.
* **Read budget (1-2 additional files).** Prevents the LLM from greedily exploring every file and blowing the context window.
* **Truncation handling.** Explicitly tells the LLM not to report truncation as an issue — a common false positive when files are large.
* **JSON-only output.** Eliminates markdown extraction headaches downstream.

## What the engine does

1. Builds the file list from (a) the user's selection if they invoked the scan manually, or (b) the 8 most-recently-modified files in the repo.
2. Reads each file up to \~3k tokens (truncates with `[...truncated]`).
3. Constructs the prompt and calls Sonnet.
4. Parses the JSON. Dedupes against `dismissedIssueIds` by computing `hash(type, filePath, line)` so re-running the scan doesn't surface the same issue twice.
5. Stores in `suggestionManager` as `codebaseIssues[]`.
6. Emits `mission_event` with `{ kind: "analysis_complete", count: N }` so the UI can render the issue cards.

## Frontend rendering

Issues appear as cards in the **Issues** drawer (one click of the toolbar icon). Each card has:

* **Accept** — spawns a fix agent with the issue's `prompt`. Hero rerouted.
* **Dismiss** — marks `dismissedIssueIds.add(hash)`. Won't reappear.

The cards live in the suggestion manager, so they survive server restarts via the persistence layer.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/apps/server/src/llm/prompts/on-demand-analysis.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.