ask

name	ask
description	Answer any question and save it as a document in docs/question/. Use for general knowledge questions, how-things-work explanations, and non-feature topics.
argument-hint	["your question"]
allowed-tools	Read, Write, Grep, Glob, WebSearch, WebFetch, Agent

Answer Question

The user asked: $ARGUMENTS

Instructions

1. Understand the question from the argument or the user's message. Identify the core topic to use as the document filename (e.g., "what is a feature flag" → feature-flag).
2. Check for an existing document using Glob("docs/question/*.md"). If a file already covers this topic, update it rather than creating a new one.
3. Research the answer thoroughly using web search, documentation, and any relevant project files.
4. Write or update the document (see Output Format) with a complete, well-structured answer.

Output Format

IMPORTANT: Every question must result in a saved document under docs/question/. Answer the question fully in the document, not just in the chat response.

Document Header

Every document must include a metadata block at the top (after the H1 title):

# Topic Title

**Version:** 1.0
**Date:** YYYY-MM-DD
**One-line summary:** ...

• Version: Start at 1.0. Increment by 0.1 for additions, 1.0 for rewrites.
• Date: Creation date — set once, never changed.
• Updated: Add this field when updating an existing document.

Required Sections

Every document must contain:

• What it is — clear definition or explanation
• Why it matters — context and significance
• How it works — mechanics, details, internals
• Practical Use Cases — 2–4 real-world scenarios with concrete examples (see format below)
• Related Topics — links to related docs (in docs/question/ or docs/features/)
• Sources — all references consulted

Practical Use Cases Format

## Practical Use Cases

### Use Case 1: <Short Title>

**Scenario:** A concrete real-world situation someone would face.

**What you do:**
The specific action, command, or decision.

**What happens / outcome:**
The result, with code blocks or examples where applicable.

Sources Section

## Sources

- [Title](URL) — one-line description
- Internal: `path/to/file.md` — what was found there

File Naming

Documents are numbered to track creation order:

1. Use Glob("docs/question/*.md") to list existing files.
2. If a file already covers the topic — update it instead.
3. If truly new: find the highest existing index prefix, increment by 1.
4. Name the file <index>-<topic-slug>.md (zero-padded to 2 digits, e.g., 01-feature-flags.md).

Steps

1. Glob existing docs; determine whether to update or create.
2. Write or update the document with correct version, date, and all required sections.
3. Provide a concise summary to the user with the key points.

This ensures the knowledge base grows across both features and general questions.