Run any Skill in Manus with one click

grob-spec-lookup

Stars3

Forks0

UpdatedJune 16, 2026 at 21:51

How to find authoritative answers to design questions in the Grob spec corpus. Use this skill when you need to verify a design decision, look up a constraint, check whether something is settled or find which spec document answers a specific question. The decisions log is the authority; this skill teaches the lookup pattern.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

grob-lang

grob-lang/grob

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Computer Occupations, All OtherComputer and Mathematical Occupations·SOC 15-1299

SKILL.md

readonly

More from this repository

same repository

writing-grob-source

grob-lang/grob

Syntax, idioms and conventions for writing .grob programs — sample scripts, integration-test fixtures, error examples. Use this skill whenever you create or edit a .grob file, so the language source is idiomatic and valid against the v1 surface. Covers bindings, the three string forms, nullability, control flow, lambdas, collection pipelines, structs, errors, the stdlib surface and numerics.

2026-07-083

allocating-an-error-code

grob-lang/grob

The single authoritative procedure for allocating a Grob error code — the pre-declared-budget model with an allocate-and-surface fallback for the unanticipated case. Use whenever an increment needs a diagnostic code: to confirm the budget covers it, to make the fold-into-existing versus register-new judgement, or to register a new code in lockstep. Codes are immutable once shipped (ADR-0017), so this keeps the design judgement explicit while making the mechanics deterministic. writing-an-error-test defers to this skill for the code itself.

2026-06-293

defining-a-type

grob-lang/grob

Use when an increment introduces, resolves or constructs a Grob type — a `type` declaration, a struct construction, an anonymous struct, a new type-annotation position, a new built-in type, or any feature where a value carries a type the checker must resolve and the VM must represent. Encodes the four failure modes that produced the Sprint 5 post-close interludes (type-reference-grammar gaps, conflated cycle walks, non-uniform redeclaration and lifecycle objects escaping through new containers) as a standing pre-flight and a closing checklist. Reuses, does not replace, `adding-an-opcode` and `tdd-cycle`.

2026-06-293

extending-the-grammar

grob-lang/grob

The sanctioned procedure for adding a parser production or an AST node to Grob — the parser/AST analogue of adding-an-opcode. Use when an increment genuinely needs a new surface form or a new node that is not already there (a new construction expression, a new literal, a new annotation position). The front end is built incrementally, so this is a real and expected job — not a wall to route around with an improvised gap-fix. It is deliberate and reviewable, never silent.

2026-06-293

writing-an-error-test

grob-lang/grob

How to add or update a gold-master error-example pair (_grob.txt + _expected.txt) and register the error code, without breaking the negative-test release gate.

2026-06-293

sonar-pr-review

grob-lang/grob

Use during a manual PR review to pull SonarQube Cloud (SonarCloud) findings for the pull request straight from the Web API — issues on new code, the quality-gate verdict and the new-code coverage against the floor — without the Docker-based Sonar MCP server. Produces a compact findings block for the reviewer to fold into its PR comment. It does not post anything; the human composes and posts the comment. Assumes the PR's Sonar scan has already completed (the reviewer is triggered manually after all scans).

2026-06-283

name	grob-spec-lookup
description	How to find authoritative answers to design questions in the Grob spec corpus. Use this skill when you need to verify a design decision, look up a constraint, check whether something is settled or find which spec document answers a specific question. The decisions log is the authority; this skill teaches the lookup pattern.

Grob spec lookup

The design corpus lives in docs/design/. The decisions log is the authority. This skill is the map.

The authority hierarchy

When two sources disagree, the higher-ranked source wins:

grob-decisions-log.md — the authority. Numbered ADR-style entries (D-001 upwards). Every meaningful design decision is recorded here with rationale, supersedes/superseded-by links and a body pointing at the spec doc for detail.
Wiki ADRs (docs/wiki/ADR/) — architecture-level decisions in full ADR format. As of May 2026, sixteen are published: ADR-0001 through ADR-0014, ADR-0016, ADR-0017. ADR-0016 is superseded by D-288 and D-291.
Live spec documents — the rest of the corpus under docs/design/. These reflect what the decisions log has settled, but if a spec doc says one thing and the decisions log says another, the log wins. Surface the drift rather than silently following one source.
Operational guidance — the Claude Code harness: the root CLAUDE.md, the nested CLAUDE.md files (src/ for C# host code, tests/, plugins/), the sub-agents under .claude/agents/ (grob-compiler-engineer, grob-reviewer, grob-design-reviewer), the slash commands under .claude/commands/, and the skills under .claude/skills/. Cannot override the decisions log; if you find a contradiction, the log wins and the operational file needs updating.

The lookup pattern

When you have a question about Grob's design, follow these steps:

Identify the question type. Most questions fall into one of these shapes:
- Behaviour question: "What should the parser do when X?"
- Constraint question: "Can Grob.Compiler reference Y?"
- Type question: "What methods does string have?"
- Format question: "How is the .grobc file laid out?"
- Scope question: "Is feature Z in Sprint 1?"
- Rationale question: "Why was approach A chosen over B?"
Pick the spec doc using the table below.
Fetch and read the relevant section. Don't load the whole file unless you need it.
Cross-check the decisions log if the answer involves a design choice. The spec doc may have lagged behind a recent decision.
Cite what you find following the conventions below.

The map

Technical and design questions only — public-facing material and historical sketches are listed at the end of this section under "Out-of-scope sources".

Question shape	Spec doc
Is decision X settled? What's the rationale?	`grob-decisions-log.md`
Has X been decided yet? (quick check)	`grob-decisions-log.md` — start at the summary index
Why was approach A chosen over approach B at the architectural level?	`docs/wiki/ADR/`
What does the parser do? Type checker? Compiler?	`grob-language-fundamentals.md`
Parser error recovery rules	`grob-language-fundamentals.md` §29
Day-one constraints (`SourceLocation`, `Declaration` back-references, two-pass type checker, error-recovering parser)	`grob-language-fundamentals.md` + the implementer agent file
What methods does built-in type T have?	`grob-type-registry.md`
What's the VM architecture? Opcodes? Stack model?	`grob-vm-architecture.md`
What's the `.grobc` binary format?	`grob-grobc-format.md`
What stdlib modules exist?	`grob-stdlib-reference.md`
What does error code Exxxx mean?	`grob-error-codes.md`
What's the error-code numbering scheme?	ADR-0014
Is error code Exxxx stable / can I change its message?	ADR-0017
What's the sprint scope? Definition of Done?	`grob-v1-requirements.md`
Which projects exist? What can reference what?	`grob-solution-architecture.md`
What are the validation suite scripts?	`grob-sample-scripts.md`
What does the formatter do?	`grob-formatter-specification.md`
What open questions remain?	`grob-open-questions.md`
What plugins are first-party?	`grob-plugins.md`
How does install work?	`grob-install-strategy.md`
What's the VS Code / LSP plan?	`grob-tooling-strategy.md`
What's the tone of error messages? REPL prompt? CLI conventions? Sparky's presentation?	`grob-personality-identity.md`

When the question doesn't fit the table, default to:

The decisions log summary index — scan for the topic.
The language fundamentals doc — most "what does Grob do?" questions live here.
project_knowledge_search with distinctive keywords from the question. Use it before reaching for arbitrary file paths.

Out-of-scope sources

These exist in the corpus but are not authoritative and should not be cited as design sources:

grob-language-brainstorm.md — early sketch notes. Historical context only.
grob-early-design-conversation.md — historical sketch transcript.
sharpbasic-retrospective.md — Grob design inputs, not Grob spec.
grob-linkedin-series-bible.md — public-facing series reference. Not a technical source.

If you find yourself wanting to cite one of these for a design question, stop. The answer either lives in an authoritative source you haven't found yet, or the question is genuinely undecided and needs a new decision.

Finding the right doc when you don't know which

Two discovery mechanisms, in order of preference:

project_knowledge_search. The fastest path to the right document when you know the topic but not the file. Search with distinctive content words from the question — type names, error codes, opcodes, module names, decision numbers. Avoid generic words like "design", "rules", "structure" that match too broadly.
The decisions log summary index. The top of grob-decisions-log.md is a numbered index of every D-### entry with a one-line summary. Scanning it is the right move for "has X been decided?" questions before reading any spec doc — if the index lists a relevant entry, jump straight to it; if it doesn't, the answer is likely either in a spec doc (use search) or genuinely undecided.

Don't load full files when you don't know which one. Search first.

Citation conventions

When you cite a source in a response, use one of these forms — never both for the same fact:

For settled design decisions: Per D-300, … or D-300 specifies …. The decisions log is the authority; citing the entry number is sufficient.
For architecture-level rationale: Per ADR-0014, …. ADR number, no file path needed.
For spec detail beyond what a decision summarises: From grob-language-fundamentals.md §29, … or grob-type-registry.md lists …. File path with section if applicable.
For operational rules: Per src/CLAUDE.md, … or Per the implementer agent, …. Full path, or the agent's name.

When a fact has both a D-### and a spec section, the D-### is the authoritative citation; the spec section is supplementary. Don't double up.

Worked examples

Example 1: a parser behaviour question

Question: "What should the parser do when it encounters an unterminated block comment?"

Lookup:

Type: behaviour question, parser-specific.
Doc: grob-language-fundamentals.md, parser section, error recovery subsection (§29).
Cross-check decisions log: D-300 covers error-recovering parser behaviour generally.
Citation: "Per D-300 and grob-language-fundamentals.md §29, the parser synchronises at statement-boundary newlines outside any open bracket, or the closing } of the enclosing block. An unterminated block comment produces an ErrorStmt with the appropriate Exxxx-series code, and recovery synchronises at the next top-level declaration keyword."

Example 2: a DAG question

Question: "Can Grob.Stdlib reference Grob.Compiler?"

Lookup:

Type: constraint question, project layout.
Doc: grob-solution-architecture.md.
Answer: No. Grob.Stdlib depends on Grob.Core and Grob.Runtime only. The DAG forbids upward references.
Citation: "Per grob-solution-architecture.md and the project-layout rules in src/CLAUDE.md, Grob.Stdlib depends only on Grob.Core and Grob.Runtime. Referencing Grob.Compiler would violate the DAG."

Example 3: a question the spec doesn't answer

Question: "What happens if a script imports two modules that export the same name?"

Lookup:

Type: behaviour question, import resolution.
Docs: grob-language-fundamentals.md (imports section), grob-v1-requirements.md (scope).
If neither doc has an answer, check grob-open-questions.md.
If still unanswered, surface the gap. Don't invent a resolution.

"I couldn't find a settled answer on duplicate-name handling across imports. grob-language-fundamentals.md covers import syntax but not collision behaviour. This may need a new decision. Should I propose one, or is there an existing source I missed?"

Example 4: a rationale question

Question: "Why is the bytecode VM stack-based rather than register-based?"

Lookup:

Type: rationale question — why, not what.
The decisions log will have a D-### entry; the wiki ADR will have the full architectural reasoning.
project_knowledge_search with "stack-based VM register" gets there fast.
Citation: "Per D-297 and ADR-0013, the VM is stack-based because I/O latency is the bottleneck for scripting workloads, not instruction dispatch; register-based complexity has no meaningful payoff for this workload."

What you do not do

Do not paraphrase the decisions log. Quote it or point to it. Paraphrasing introduces drift.
Do not resolve drift in your head. If two sources disagree, the log wins, but surface the inconsistency so the lagging source can be fixed.
Do not invent decisions. If the spec is silent on something, the gap is itself a finding. Propose a decision; don't backfill one.
Do not load the whole corpus to answer a single question. Fetch what you need.
Do not cite from memory. Always re-fetch when precision matters. The spec evolves; old assumptions go stale.
Do not cite supplementary sources as authority. The brainstorm and early-design files are background, not source of truth.

When an authoritative document is wrong

Sometimes you'll find an actual error in an authoritative document — a contradiction between two sections, a stale reference to a superseded decision, a typo that changes meaning. This applies to any document with authority: spec docs, decisions log entries, ADRs, instruction files, agent files, skills.

When this happens:

Don't fix it silently. These documents have authority because they're trustworthy; silent fixes erode that.
Surface the finding. "In grob-vm-architecture.md §4.3, the opcode list shows OP_LOAD at byte 0x12, but D-298 specifies 0x14. The decisions log is authoritative; the spec doc has drifted. Should I propose a fix?"

Or: "The reviewer agent checks [ExcludeFromCodeCoverage] justifications, but src/CLAUDE.md doesn't actually state what counts as substantive. The instruction file should be the source; the reviewer is enforcing a rule the instruction file doesn't quite spell out. Should I propose tightening the instruction file?"
Wait for Chris's call. Edits to authoritative documents are deliberate, not casual. The fix path may be a decisions log entry, a spec edit, an instruction-file update, or all three — Chris decides which.