Asking questions about your project

The short answer

You can ask your AI tool questions about your project, such as "which module owns invoicing?", and Paqad routes them to its project-question workflow. In that workflow the AI is told to check your documentation first, then the code, and to change nothing. The quality of the answer depends on your documentation and on the AI.

The paqad-ai package also contains a structured answer builder that labels an answer with how well it is supported, cites its sources, and flags stale or conflicting evidence. In 1.91.1 that builder is available to code that uses the package as a library. No Paqad command or hook calls it, so your AI tool's answers do not carry these labels automatically.

What happens when you ask a question

1. Paqad's router classifies the prompt. A question about the codebase with no requested change goes to project-question, on the fast lane. See Workflow routing.
2. The router instructions tell the AI to read docs/ first, then the code, and not to change anything.
3. If retrieval is switched on, Paqad adds a few passages from your documentation that match the question. See the RAG overview.
4. The AI writes the answer. This last step is model judgment.

Good module documentation under docs/modules/ makes the biggest difference. You create it with the Paqad documentation workflow: ask your AI tool to create documentation, then create module documentation.

The structured answer builder

The package exports ProjectKnowledgeAnswerer. Given a question, a project folder and an answer mode, it returns an answer object built entirely by scripts: keyword matching and file checks, with no AI model. It is useful if you build your own tool on top of paqad-ai and want answers that show their evidence.

How it finds evidence

It removes common words from the question and keeps the keywords. It then scores files by how many keywords they contain, looking in this order of preference:

Source class	Files searched
canonical-doc	docs/modules/**/*.md
generated-instruction	docs/instructions/**/*.md
framework-state	.paqad/**/*.{json,yaml,yml}
manifest	package.json, composer.json, go.mod, Cargo.toml, pyproject.toml, pom.xml at the project root
workflow	.github/workflows/**/*.{yml,yaml}
code	.ts and .js files under src/, app/ or lib/

Files with more keyword matches rank first. The order above only breaks ties. When retrieval is switched on and its index is valid, matching passages from the index are added to the candidates. The top six files become the evidence.

Grounding states

• observed: the top piece of evidence is a module document under docs/modules/.
• inferred: evidence was found, but the top piece is something else, such as a manifest or framework state file.
• missing-evidence: nothing matched. The answer suggests running paqad-ai onboard to generate documentation.

Answer modes

Mode	What the answer text contains
quick	The lead finding with its file, plus the first freshness note and any conflict note.
explain	The lead finding, up to two supporting findings, all freshness notes and any conflict note.
trace	Everything in explain, plus a numbered list of every piece of evidence with its source class and a short excerpt.

Every answer object also includes citations (path, source class and an excerpt), next_actions and a plain confidence_basis sentence explaining the grounding state.

Freshness

If .paqad/doc-progress.json exists, its generated_at time is the documentation baseline. Any cited file modified more than 24 hours after that baseline is listed in stale_sources, because it has changed since the documentation was generated. If .paqad/stack-drift.json exists and is not empty, drift_detected is set. If there is no baseline file, freshness is reported as unknown rather than fresh. Stale sources add the suggestion to run paqad-ai update.

Conflicting evidence

The builder compares a small set of facts across the evidence excerpts: the Node.js engine version, the version field and the pnpm version. When two files state different values for the same fact, both files are named in contradictions. Conflicts never hide the answer; they are reported alongside it. Conflicts about other topics are not detected.