grill-me-with-docs

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Grill Me with Docs

The comprehensive entry point into an ambiguous problem or architectural initiative. This skill combines the relentless 1-at-a-time decision interview of `/grilling` with active domain modeling and decision capture.

## The Workflow

```text
Problem / Idea
  │
  ├── 1. Relentless Interview Loop (1 decision at a time with recommendations)
  │     ├── Automated fact-finding via codebase / documentation
  │     └── User-confirmed decisions across the design tree
  │
  ├── 2. Live Domain Modeling
  │     └── Update CONTEXT.md whenever vocabulary or boundaries crystallize
  │
  ├── 3. Architectural Decision Records (ADRs)
  │     └── Create docs/adr/000X-*.md when hard-to-reverse trade-offs are settled
  │
  └── 4. Shared Understanding Confirmed → Handoff to /to-spec or /to-tickets
```

## 1. The Interview Loop

- **One decision at a time.** Walk the branches of the design tree sequentially.
- **Provide clear recommendations.** State options with pros/cons, flagging the recommended path.
- **Find facts autonomously.** Inspect the filesystem, code, and configs before asking.
- **Use interactive tooling.** Use `ask_question` or structured selection prompts where available.

## 2. Real-time Glossary (`CONTEXT.md`)

As terms, boundaries, and concepts are clarified during the interview, record them immediately in `CONTEXT.md`. Do not wait until the end of the session.

- **Check against existing terms:** Call out conflicting or overloaded words ("You said 'account' - do you mean Customer or User?").
- **Keep it free of implementation details:** `CONTEXT.md` is a ubiquitous language glossary, not a technical spec.
- Follow standard ubiquitous language glossary conventions: definitions, boundary rules, and rejected terms.

## 3. Recording Architectural Decision Records (ADRs)

Only create an ADR when a settled decision meets all three criteria:

1. **Hard to reverse** - High cost to change later (e.g. database choice, communication protocol, core boundary).
2. **Surprising without context** - Future engineers would ask "why did they build it this way?".
3. **Real trade-off** - Chosen among genuine alternatives with distinct advantages and disadvantages.

When all three are met, create `docs/adr/000X-slug.md` documenting context, decision, and consequences.

## 4. Closing the Session

The session finishes when:

1. All open branches of the design tree are explored and settled.
2. The `CONTEXT.md` glossary reflects all defined domain terms.
3. Key hard-to-reverse choices are recorded in `docs/adr/`.
4. The user explicitly confirms shared understanding.

## Handoffs

- **To Technical Spec:** Run `/to-spec` to synthesize the settled architecture into an issue or PRD.
- **To Backlog Decomposition:** Run `/to-tickets` to break the decisions down into atomic, dependency-mapped tickets.
- **Pure Interview:** If no glossary or ADR documentation is needed, reach for `/grilling`.

From MAHDTech/agent-skills, MIT.

More from MAHDTech/agent-skills