Index of every page on this site: llms.txt
All skills
flutter avatar

/grill-with-docs

@ff6d472 official
by flutterflutter/agent-plugins3.2k stars
193
Run it yourself

Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.

Use this Skill: https://skilld.dev/gh/flutter/agent-plugins/grill-with-docs

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈74 tokens for metadata: the name and description. ≈807 when used: this file. ≈1.5k more on demand in 2 files.

Description uses 3.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈296 characters, or 3.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

<what-to-do>

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

Ask the questions one at a time, waiting for feedback on each question before continuing.

If a question can be answered by exploring the codebase, explore the codebase instead.

</what-to-do><supporting-info>

Domain awareness

During codebase exploration, also look for existing documentation:

File structure

Most repos have a single context:

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

If a CONTEXT-MAP.md exists at the root, the repo has multiple contexts. The map points to where each one lives:

/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                          ← system-wide decisions
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md
│   │   └── docs/adr/                 ← context-specific decisions
│   └── billing/
│       ├── CONTEXT.md
│       └── docs/adr/

Create files lazily — only when you have something to write. If no CONTEXT.md exists, create one when the first term is resolved. If no docs/adr/ exists, create it when the first ADR is needed.

During the session

Challenge against the glossary

When the user uses a term that conflicts with the existing language in CONTEXT.md, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"

Sharpen fuzzy language

When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."

Discuss concrete scenarios

When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.

Cross-reference with code

When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"

Update CONTEXT.md inline

When a term is resolved, update CONTEXT.md right there. Don't batch these up — capture them as they happen. Use the format in CONTEXT-FORMAT.md.

Don't couple CONTEXT.md to implementation details. Only include terms that are meaningful to domain experts.

Offer ADRs sparingly

Only offer to create an ADR when all three are true:

  1. Hard to reverse — the cost of changing your mind later is meaningful
  2. Surprising without context — a future reader will wonder "why did they do it this way?"
  3. The result of a real trade-off — there were genuine alternatives and you picked one for specific reasons

If any of the three is missing, skip the ADR. Use the format in ADR-FORMAT.md.

</supporting-info>

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts3mo3 checks · Risk SAFE
  • Gen Agent Trust Hub3mo

    The skill provides a structured method for refining project documentation, glossaries, and architectural decisions through an interactive interview process. It focuses on internal project consistency and does not perform any dangerous operations.

  • Socket3mo

    No alerts

  • Snyk3mo

    Risk: LOW · No issues

Signed by skilld at ff6d472. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 6 months ago
  • Documentation
  • domain-driven-design
  • planning
  • adr
  • terminology
  • codebase-exploration
  • design-review
  • context-mapping

README badge

README badge for flutter/agent-plugins/grill-with-docs

Conducts a structured interview of your design plan against existing domain terminology and documented decisions, surfacing conflicts and gaps in the codebase. Updates CONTEXT.md and ADRs inline as the conversation resolves each decision point.

Generated from the current SKILL.md.

What's the difference between this skill and a standard code review or design doc feedback session?
This skill systematically challenges your plan against your project's existing domain model, terminology, and documented decisions (CONTEXT.md and ADRs), then updates those docs inline as ambiguities are resolved. It's not just critique — it's domain alignment plus documentation maintenance in one session.
Does this skill explore my codebase, or does it only work from what I tell it?
It actively explores your codebase to answer questions and validate claims. If a question can be resolved by reading code, it will do that instead of asking you. It also searches for existing CONTEXT.md and ADR files to cross-reference against.
Will this create new documentation files, or just update existing ones?
It creates files lazily — only when you've resolved something that needs to be captured. It will create CONTEXT.md on first use if it doesn't exist, and create docs/adr/ only when an ADR is genuinely needed (hard to reverse, surprising without context, result of a real trade-off).
How does this handle repos with multiple bounded contexts?
If your repo has a CONTEXT-MAP.md at the root, the skill recognizes you have multiple contexts and looks for CONTEXT.md and docs/adr/ folders within each context directory (e.g. src/ordering/CONTEXT.md).

Generated from the current SKILL.md. These answers refresh after source changes.