{"id":17539,"plugin_id":"plugins_6a78e83987748191afc0c56e12172fce","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:14:15.241Z","digest":"f66d318275c101f7170fc27062fbf0e80c41f44a5d799b726d270a13f9d35bc0","against":null,"payload":{"description":"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.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":102}],"name":"grill-with-docs","skill_md_contents":"---\nname: grill-with-docs\ndescription: \"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.\"\n---\n\n# Grill with Docs\n\nConduct 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`).\n\n---\n\n## Core Invariants\n\n1. **Simultaneous Documentation Distillation**: Extract and record ubiquitous domain language into `CONTEXT.md` and architectural choices into ADRs in real time as decisions settle.\n2. **Batch Frontier Questioning**: Present independent frontier questions in structured batches with explicit defaults rather than one-off queries.\n3. **Autonomous Fact Reconnaissance**: Research existing codebase architecture, types, and schemas autonomously before posing design questions.\n4. **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.\n5. **Zero Speculative Prose**: Document only decisions that have actively settled during the interview; keep draft notes clearly demarcated.\n\n---\n\n## Architecture & Map of Content (MOC)\n\n```\n[ User Feature Idea ] ──► [ Codebase Recon & ADR Review ] ──► [ Socratic Grilling Rounds ]\n                                                                       │\n                                      ┌────────────────────────────────┴────────────────────────────────┐\n                                      ▼                                                                 ▼\n                            [ Update CONTEXT.md ]                                              [ Author ADR Docs ]\n                            - Ubiquitous language                                              - Context & Decision\n                            - Entity definitions                                               - Consequences & Tradeoffs\n```\n\n| Artifact | Purpose | Reference Format |\n|---|---|---|\n| **Domain Dictionary** | Capture ubiquitous language and entity relationships | `skills/domain-modeling/CONTEXT-FORMAT.md` |\n| **Architectural Record** | Record irreversible architectural choices | `skills/domain-modeling/ADR-FORMAT.md` |\n| **Grilling Protocol** | Drive structured frontier question rounds | `skills/grilling/SKILL.md` |\n\n---\n\n## Step-by-Step Procedure (TWI)\n\n### Step 1: Discover Existing Documentation Baseline\n- **Action**: Check for existing `CONTEXT.md`, `GLOSSARY.md`, and `docs/adr/` records in the repository.\n- **Key Point**: Adopt existing project conventions for domain modeling and decision logging.\n- **Why**: Maintaining architectural consistency prevents duplicate terminology and fragmented records.\n\n### Step 2: Conduct Socratic Grilling Rounds\n- **Action**: Identify unsettled requirements and formulate numbered question rounds with recommended defaults.\n- **Key Point**: Ask about boundaries, invariants, entity lifecycles, and failure recovery.\n- **Inline Checklist**:\n  - [ ] Terminology vetted against existing domain dictionary\n  - [ ] Questions formatted with clear recommendations\n  - [ ] Architecture tradeoffs highlighted\n\n### Step 3: Distill and Update Domain Glossary\n- **Action**: As terms and entities are clarified, update or create `CONTEXT.md` using the standard format.\n- **Key Point**: Ensure terms are strictly defined with unambiguous scope.\n- **Why**: Shared ubiquitous language prevents misalignment between engineers and agents.\n\n### Step 4: Author Architectural Decision Records (ADRs)\n- **Action**: For significant architectural choices, author a new numbered ADR in `docs/adr/NNNN-<slug>.md`.\n- **Key Point**: Include Context, Decision, Status, and Consequences (both positive and negative).\n- **Why**: ADRs preserve institutional memory and prevent rehashing past debates.\n\n---\n\n## Anti-Rationalization Guardrails\n\n| Tempting Rationalization | Binding Rule | Engineering Rationale |\n|---|---|---|\n| *\"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. |\n| *\"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. |\n| *\"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. |\n\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}