Skip to content

I'll analyze the code to understand the command structure. Let me inspect the referenced packages to ensure accurate documentation.I have enough context. The ask command currently returns ErrNotImplemented but the underlying answer package describes its intended behavior. Let me check the compose file briefly for completeness.--- title: phpbotscout ask description: Answer a question from the indexed documentation, with citations, or honestly decline when the corpus does not cover it. date: 2026-07-28 tags: [cli, command, ask, documentation, answer, rag] authors: [Claude (claude-opus-4-8)]

phpbotscout ask

The ask command answers a question using only the documentation phpbotscout has already indexed. When the indexed corpus contains an answer, it returns grounded prose backed by citations. When it does not, it declines — honestly and by design — rather than inventing something plausible.

Status: not yet implemented

This command is scaffolded but its handler currently returns a "not implemented" error. The behaviour described below reflects the intended design captured in the underlying pkg/answer package. Running the command today will return an error until the feature is wired up.

Usage

phpbotscout ask [flags]

Description

phpbotscout ask turns a question into a grounded answer, or into an honest refusal to answer.

The command retrieves the most relevant passages from the indexed documentation, then asks a language model to compose an answer using only those passages. Every substantive claim in the reply must be traceable to a specific, cited passage that was actually retrieved.

Declining is treated as a first-class outcome, not a failure. There are three situations in which the command will decline instead of answering:

  • Nothing matched. Retrieval returned no passages relevant to the question, so there is nothing to ground an answer in.

  • The composer declined. The passages discuss the subject but do not actually answer the question — a common and especially damaging trap, because the resulting answer would look well sourced while being wrong.

  • The answer could not be grounded. A draft answer was produced, but it cited nothing (see ErrUngrounded) or cited a passage outside the retrieved set (see ErrFabricatedCitation). Publishing such an answer is exactly the failure this command exists to prevent, so it is downgraded to a decline.

Why declining matters

A declined question is a knowledge gap with a timestamp on it. This is deliberate: the stream of unanswered questions is intended to become a self-writing, prioritised documentation backlog. A decline is an outcome to act on, not an error to suppress.

Answers are grounded, not guessed

The model is instructed to use only the supplied documentation passages and to ignore anything it may "know" about the projects from elsewhere. Passages are treated as untrusted content and fenced within explicit delimiters, so text inside a passage is never interpreted as an instruction.

An actual error (a non-zero exit) is reserved for something genuinely breaking — for example, the index being unreachable or the model provider failing. An error never means "we do not know"; that is a decline. Keeping the two distinct is what allows a knowledge gap to be told apart from an incident.

Flags

This command inherits the global flags provided by phpbotscout (run phpbotscout ask --help to see them). It does not currently define any command-specific flags.

Name Description Default Required
-h, --help Show help for the ask command. false No

Retrieval defaults

Internally, answering retrieves a default of 8 passages per question (DefaultLimit). This is a library-level default in pkg/answer and is not yet exposed as a command-line flag.

Examples

Ask a question directly:

$ phpbotscout ask "How do I install the tool?"

Ask a longer, quoted question:

$ phpbotscout ask "What environment variable overrides the log level?"

View the command's help:

$ phpbotscout ask --help

An expected answer is grounded in the documentation and includes citations:

Install the latest release with `go install`, using the /cmd/phpbotscout path.

Sources:
  [1] Install — https://.../#install

When the corpus does not cover the question, the command declines instead of guessing:

Declined: nothing in the indexed documentation matched this question.