Question Router
b1uelake/question-router
Roteia perguntas para respostas estruturadas e validadas de alta qualidade
Ver no GitHubFramework agnóstico que classifica perguntas e as roteia para contratos de resposta estruturados, garantindo respostas de alta qualidade. Implementa um pipeline de validação que identifica contexto insuficiente, faz perguntas de esclarecimento direcionadas e aplica estruturas de resposta específicas por tipo de questão.
Instalação
npx convez-ai b1uelake/question-router1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Melhorar qualidade de respostas de assistentes IA em aplicações
- Estruturar respostas em sistemas de suporte técnico ou educação
- Validar completude e correção de respostas antes de finalizar
Veredito

Skill sólida e bem documentada para aumentar qualidade de respostas em qualquer agente LLM. Proposta agnóstica ao framework é um diferencial real, mas requer integração manual no seu pipeline.
README
A tradução para o português deste README ainda está na fila.
Question Router
A framework-agnostic prompting methodology that turns under-specified questions into well-framed, high-quality answers. It classifies the request, checks context sufficiency, asks only necessary clarifying questions, loads the relevant response contract, and validates the answer before finalizing.
The instructions work as a system prompt for any LLM-based agent — Claude Code, Codex, Cursor, Windsurf, ChatGPT, LangChain, or your own custom agent. The repo happens to use the Codex skill format (YAML frontmatter + markdown), but the methodology itself is platform-independent.
How It Works
The skill routes every question through a structured pipeline:
- Classify — determine the primary question type
- Check context — identify missing information that would materially change the answer
- Clarify (if needed) — ask the fewest useful questions (1–3, max 5)
- Load contract — apply a type-specific response structure
- Validate — run a quality gate before finalizing
Six Question Types
| Type | Use For | Example |
|---|---|---|
learning | Concepts, explanations, learning paths | "What is pytest?" |
analysis | Causes, tradeoffs, comparisons, "why" questions | "Why do startups choose microservices?" |
decision | Choosing, prioritizing, adopting | "Should I use React or Vue?" |
plan | Roadmaps, study plans, step-by-step sequences | "Build me a 10-week AI study plan" |
risk | Failure modes, security, compliance, safety | "Is it safe to skip GDPR compliance?" |
technical | Implementation, debugging, architecture | "My API returns 502 under load" |
Answer Structure
Every full answer includes nine mandatory elements:
- Problem type — classification and framing
- Assumptions — what was inferred from incomplete context
- Known facts — source-backed or widely established
- Reasonable inferences — what follows from known facts
- Recommendations — actionable guidance with confidence level
- Uncertainty / needs verification — what should be checked
- Judgment standards — criteria used to evaluate options
- Counterexamples or failure cases — where the answer breaks
- Prioritized next actions — ordered, concrete steps
For simple beginner questions, a compact mode compresses this into: type, direct answer, why it matters, example, next step.
Repository Structure
question-router/
├── SKILL.md # Skill definition and core workflow
├── references/ # Response contracts per type
│ ├── learning.md
│ ├── analysis.md
│ ├── decision.md
│ ├── plan.md
│ ├── risk.md
│ └── technical.md
├── evals/
│ └── evals.json # Regression test cases
├── schemas/
│ ├── eval-case.schema.json # JSON Schema for eval cases
│ └── route.schema.json # JSON Schema for internal route objects
└── scripts/
├── validate_skill.py # Validate skill structure and evals
├── build_promptfoo_config.py # Generate promptfoo eval config
└── run_evals.sh # Full eval pipeline (validate → build → run)
Usage
This methodology works with any LLM agent. Choose the approach that fits your setup:
As a Codex / Claude Code skill
git clone https://github.com/b1uelake/question-router.git ~/.codex/skills/question-router
The skill auto-activates when you ask broad, vague, or complex questions.
As a system prompt (any agent)
Copy SKILL.md + the relevant references/*.md into your system prompt or custom instructions. The files are plain markdown — no special format required.
As a LangChain / custom agent prompt
Load SKILL.md and the reference contracts into your agent's instruction template. The eval suite in evals/evals.json provides regression test cases you can use with your own eval pipeline.
Running Validation
cd ~/.codex/skills/question-router
python3 scripts/validate_skill.py
Running Eval Suite
# Requires promptfoo: npm install -g promptfoo
# The scripts below use promptfoo to run assertions defined in evals/evals.json
bash scripts/run_evals.sh
The eval scripts default to a Codex-style HTTP API endpoint. To use a different provider (OpenAI, Anthropic, etc.), pass a custom config or edit scripts/build_promptfoo_config.py.
Codex-Specific Format
The repo uses Codex's skill format (SKILL.md with YAML frontmatter). This is a thin wrapper — the core methodology lives in the reference contracts and the classification logic in SKILL.md, both of which are plain markdown. You can strip the YAML frontmatter and use the rest with any agent framework.
Design Principles
- Don't guess when you can ask. Missing context that materially changes the answer triggers clarification (1–3 questions, never more than 5).
- Don't clarify when you can assume. If a safe default handles the ambiguity, state it and proceed.
- Structure scales with complexity. Simple beginner questions get compact mode; high-stakes decisions get the full nine-part structure.
- Separate facts from inference from advice. The reader should always know which is which.
- Every recommendation needs criteria. "Choose X" without "because Y under condition Z" is incomplete.
- Mark verification needs. Legal, compliance, pricing, and source-dependent claims must be flagged for verification.
License
MIT