agentleFS
Sign inStart free
imMamdouhaboammarimMamdouhaboammar/matts-skills-into-chatgpt/skills/grill-with-docs/SKILL.md

grill-with-docs

Skill8 starsChanged 2 months agoMITView on GitHub

Interview the user to stress-test a design while simultaneously recording domain terms and architectural decisions in project documentation. Use when planning features in a codebase and wanting domain terms captured in CONTEXT.md and ADRs — even if the user says \"grill this feature\". Do NOT use when no codebase context or documentation trail is needed.

We split this skill into the rules it gives an agent

5 rules. 0 are common, 4 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 178 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Lightweight ADR Trigger: When a design choice creates significant technical debt or is difficult to reverse (e.g.

    line 17
  2. Distinctive:

    Zero Speculative Prose: Document only decisions that have actively settled during the interview.

    line 18
  3. Very specific:

    Action: Check for existing CONTEXT.md, GLOSSARY.md, and docs/adr/ records in the repository.

    line 45
  4. Distinctive:

    Key Point: Ask about boundaries, invariants, entity lifecycles, and failure recovery.

    line 51
  5. Distinctive:

    Key Point: Ensure terms are strictly defined with unambiguous scope.

    line 59

“Common” is measured: kept by at least 6 in 10 of the 178 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Grill with Docs

Conduct a structured Socratic design interview that concurrently distills and commits domain terminology into CONTEXT.md and hard-to-reverse architectural decisions into Architectural Decision Records (docs/adr/*.md).

Core Invariants

  1. Simultaneous Documentation Distillation: Extract and record ubiquitous domain language into CONTEXT.md and architectural choices into ADRs in real time as decisions settle.
  2. Batch Frontier Questioning: Present independent frontier questions in structured batches with explicit defaults rather than one-off queries.
  3. Autonomous Fact Reconnaissance: Research existing codebase architecture, types, and schemas autonomously before posing design questions.
  4. Lightweight ADR Trigger: When a design choice creates significant technical debt or is difficult to reverse (e.g. database choice, sync strategy), write a dedicated ADR immediately.
  5. Zero Speculative Prose: Document only decisions that have actively settled during the interview; keep draft notes clearly demarcated.

Architecture & Map of Content (MOC)

[ User Feature Idea ] ──► [ Codebase Recon & ADR Review ] ──► [ Socratic Grilling Rounds ]
                                                                       │
                                      ┌────────────────────────────────┴────────────────────────────────┐
                                      ▼                                                                 ▼
                            [ Update CONTEXT.md ]                                              [ Author ADR Docs ]
                            - Ubiquitous language                                              - Context & Decision
                            - Entity definitions                                               - Consequences & Tradeoffs
ArtifactPurposeReference Format
Domain DictionaryCapture ubiquitous language and entity relationshipsskills/domain-modeling/CONTEXT-FORMAT.md
Architectural RecordRecord irreversible architectural choicesskills/domain-modeling/ADR-FORMAT.md
Grilling ProtocolDrive structured frontier question roundsskills/grilling/SKILL.md

Step-by-Step Procedure (TWI)

Step 1: Discover Existing Documentation Baseline

  • Action: Check for existing CONTEXT.md, GLOSSARY.md, and docs/adr/ records in the repository.
  • Key Point: Adopt existing project conventions for domain modeling and decision logging.
  • Why: Maintaining architectural consistency prevents duplicate terminology and fragmented records.

Step 2: Conduct Socratic Grilling Rounds

  • Action: Identify unsettled requirements and formulate numbered question rounds with recommended defaults.
  • Key Point: Ask about boundaries, invariants, entity lifecycles, and failure recovery.
  • Inline Checklist:
    • Terminology vetted against existing domain dictionary
    • Questions formatted with clear recommendations
    • Architecture tradeoffs highlighted

Step 3: Distill and Update Domain Glossary

  • Action: As terms and entities are clarified, update or create CONTEXT.md using the standard format.
  • Key Point: Ensure terms are strictly defined with unambiguous scope.
  • Why: Shared ubiquitous language prevents misalignment between engineers and agents.

Step 4: Author Architectural Decision Records (ADRs)

  • Action: For significant architectural choices, author a new numbered ADR in docs/adr/NNNN-<slug>.md.
  • Key Point: Include Context, Decision, Status, and Consequences (both positive and negative).
  • Why: ADRs preserve institutional memory and prevent rehashing past debates.

Anti-Rationalization Guardrails

Tempting RationalizationBinding RuleEngineering Rationale
"I'll write the documentation after the entire interview finishes."Capture terms and ADRs as decisions settle.Post-hoc documentation often drops subtle nuances, tradeoffs, and rationale.
"This architectural choice is minor, no ADR needed."If it is hard to reverse, author an ADR.Seemingly minor choices often cascade into major technical debt.
"I will ask the user to explain the existing domain model."Read existing docs and schemas autonomously.Agents must build initial context from repo artifacts before engaging the user.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free