grill-with-docs

Run design grilling while maintaining the shared glossary and ADR trail.

SKILL.md

GitHub
<!-- Generated by mstack from Misbah's Build Like This workflow. Regenerate instead of editing. -->

grill-with-docs

This skill is part of Misbah Khursheed's Build Like This workflow. Thinking, evidence, and explicit trade-offs come before generated output.

Project identity and sources of truth

The repository where this skill is installed is the host project being built. Build Like This is the method used to build it; mstack only installs and reconciles method resources. Do not assume mstack or Build Like This is the product unless project-owned sources explicitly identify this repository as mstack itself.

Use project-owned docs/, decisions, executable code, and tests as sources of truth. .mstack/templates/ are reference scaffolds to copy and adapt into project-owned documents, not product requirements and not a replacement for docs/.

Purpose

Keep shared language and hard-to-reverse decisions durable as the interview proceeds, so later agents inherit terms and trade-offs instead of rediscovering them.

Required inputs

  • The same inputs as design-grilling, plus current docs/glossary.md and docs/decisions/ when present.
  • planning-setup output or defaults for where glossary and ADRs live.

If a missing input would materially change the result, state the gap and obtain or discover it before proceeding. Otherwise label the assumption and continue.

Process

  1. Invoke the design-grilling process for the decision frontier.
  2. When a term is loaded or contested, update docs/glossary.md with preferred wording, avoided synonyms, and relationships; flag unresolved ambiguity instead of forcing a fake definition.
  3. When a choice is hard to reverse, surprising, or trades material cost for benefit, draft or update a short ADR under docs/decisions/ using the project ADR template.
  4. Keep product.md and architecture.md updates for their owning phases; only record the decisions and language those phases will consume.
  5. Run or cite mstack validate so glossary and decision checks stay visible.
  6. Hand off the confirmed ledger plus glossary/ADR pointers to the next lifecycle prompt.

Output contract

  • Updated or created docs/glossary.md and any new or revised ADR files with confirmed decisions only.
  • Decision ledger linking each consequential choice to glossary terms and ADR paths.
  • Validation notes for GLOSSARY and DECISIONS checks.

Guardrails

  • Do not create an ADR for reversible micro-choices or pure implementation detail.
  • Do not invent glossary terms that change no decision.
  • Do not silently overwrite user-owned glossary or ADR prose; merge with explicit conflict callouts.

Delegation and parallel safety

  • Material lifecycle work must delegate at least one bounded specialist lane when subagents are available. Prefer two or more concurrent lanes only for independent evidence gathering, analysis, or non-overlapping file ownership.
  • The active lead owns integration and acceptance. Supporting agents do not recursively delegate unless explicitly promoted to lead a named lane.
  • Assign distinct outputs and ownership. Serialize shared docs, contracts, schemas, migrations, deployments, external writes, and overlapping file edits.
  • When subagents are unavailable, perform the same named specialist passes sequentially and state that constraint instead of implying parallel verification.
  • Delegation never grants permission for outreach, consequential external actions, destructive changes, paid resources, or production operations.

End with the evidence gathered, verification performed, and any residual risk or unresolved decision.