| name | store-query-grammar |
| description | Reference for the Forge NLP query grammar — entity synonyms, status synonyms, ordering tokens, FK phrases, and ID patterns. Use when constructing or debugging store-query-nlp queries, or to understand why a query returned unexpected results. |
| allowed-tools | ["Bash"] |
forge:store-query-grammar
NLP grammar reference for the Forge store query engine.
The query engine (store-cli.cjs nlp) uses a 5-stage deterministic rule-based
parser — no LLM, no network. This skill documents the token vocabulary so you
can construct precise queries and debug unexpected parse results.
Setup
Dump the live grammar for the current project (includes project-specific ID patterns):
FORGE_ROOT=$(node -e "console.log(require('./.forge/config.json').paths.forgeRoot)")
node "$FORGE_ROOT/tools/store-cli.cjs" schema
The schema command returns entity schemas, status enums, and the full grammar
reference for the installed project prefix.
Parser Stages
Stage 1 — ID Patterns (highest priority)
Matched first; consumed tokens are excluded from later stages.
| Pattern | Example | Resolves to |
|---|
{PREFIX}-S##-T## | WI-S12-T03 | task filter |
{PREFIX}-BUG-### | WI-BUG-047 | bug filter |
FEAT-### | FEAT-003 | feature filter |
S## | S12 | sprint filter |
sprint N | sprint 12 | sprint filter → S12 |
Stage 2 — Entity Detection
The parser identifies the primary entity type from synonyms. First match wins.
| Entity | Synonyms |
|---|
| sprints | sprint, sprints, release, releases, iteration, iterations |
| tasks | task, tasks, item, items, work item, work items, todo, todos |
| bugs | bug, bugs, defect, defects, issue, issues, problem, problems |
| features | feature, features, epic, epics, capability, capabilities |
Bigrams are matched before unigrams (e.g. work item → tasks).
Stage 3 — Status / Severity Filters
Maps natural-language status phrases to schema enum values per entity type.
| Input phrase | tasks | bugs | sprints | features |
|---|
| open / active / in progress | implementing | in-progress | active | active |
| completed / done | committed | fixed | completed | shipped |
| fixed | — | fixed | — | — |
| planned / planning | planned | — | planning | — |
| implementing | implementing | — | — | — |
| implemented | implemented | — | — | — |
| committed | committed | — | — | — |
| draft | draft | — | — | draft |
| abandoned | abandoned | — | abandoned | — |
| retired | — | — | — | retired |
| shipped | — | — | — | shipped |
| triaged | — | triaged | — | — |
| reported | — | reported | — | — |
| blocked | blocked | — | — | — |
Severity (bugs only, sets severity field not status):
| Input | Severity |
|---|
| critical | critical |
| major | major |
| minor | minor |
Stage 4 — FK Follow Phrases
Trigger FK traversal in the result set.
| Phrase | FK followed |
|---|
| with sprint / sprint for / which sprint | sprintId |
| with feature / feature for | featureId |
| block / blocking / blocked | blocksTask (for bugs) or blockedBy (for tasks) |
Stage 4b — Ordering and Limit Tokens
| Token(s) | Effect |
|---|
| latest / newest / recent / most recent | sort desc, limit 1 |
| oldest / earliest / first | sort asc, limit 1 |
| last | sort desc, limit 1 |
| top N / first N | sort desc/asc, limit N |
| last N | sort desc, limit N |
| how many / count of / number of / count | count mode (returns {count: N}) |
Stage 5 — Keyword Extraction
Remaining tokens (not consumed by stages 1–4, not in stop words, length > 1)
become keyword match terms on the title field (word-boundary match).
Stop words include all entity synonyms plus: list, all, the, show, find, what,
which, are, in, for, about, related, to, of, and, with, details, status, how,
many, there, a, an, is, that, this, on, by, me, give, get, tell, please, can,
do, does, did, was, were, been, being, have, has, had, will, would, could,
should, may, might, blocking, blocked, block, severity, titles, title.
Debugging Queries
If a query returns unexpected results, use traversalTrace in the output:
"traversalTrace": [
"intent parsed via NLP rules",
"listed tasks with filter {\"status\":\"implementing\"}: 7 results",
"sorted tasks desc",
"limited to 3 (of 7)",
"plan confidence: high"
]
Common debug patterns:
| Symptom | Likely cause |
|---|
| 0 results, retried | Status phrase didn't map to a valid enum for the detected entity type |
| confidence: low | Filter value stripped — check the status mapping table above |
| Wrong entity type | Entity synonym matched a stop word before the intended synonym |
| Keyword matching too broadly | Term is short (≤1 char) or in stop words; try a more specific term |
| Missing FK traversal | FK phrase not in stage 4 vocabulary; use --with-sprint / --with-feature flags instead |
Query Composition Tips
- Put entity type first:
"bugs in S12" not "S12 bugs" — entity is detected in order
- Use exact ID when known:
"WI-BUG-047" is faster and more precise than "bug about auth"
- Count before listing:
"how many open bugs" before "open bugs" for large stores
- Combine stages naturally:
"critical open bugs in S12 blocking tasks" uses stages 1, 2, 3, 4 together
