About

Imported from akillness/jeo-skills (.agent-skills/grill-with-docs/SKILL.md) via skills.sh. Install upstream with npx skills add akillness/jeo-skills --skill grill-with-docs. Copyright stays with the author.

Grill With Docs

Name: grill-with-docs
Author: akillness

A grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation inline as decisions crystallize.

When to use this skill

Validating architectural plans against a project's domain language
Stress-testing designs before implementation
Updating CONTEXT.md terminology as new concepts emerge
Preparing issues for implementation (pairs with triage)

When not to use this skill

Finding refactoring opportunities → use improve-codebase-architecture
Writing implementation tickets → use to-issues
General code review → use code-review

Session process

1. Explore domain context

Before grilling, read:

CONTEXT.md — existing domain terminology
docs/adr/ — prior architectural decisions
Relevant source files to understand current state

2. Run the grilling loop

Interview relentlessly about every decision point. For each question:

Provide a recommended answer
Ask one question at a time, waiting for feedback before continuing
Explore the codebase instead of asking when the answer is findable there

3. Three stress-test mechanisms

Glossary alignment — When the user uses a term that conflicts with CONTEXT.md, call it out:

"Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"

Precision sharpening — When terms are vague or overloaded, propose canonical names:

"You're saying 'account' — do you mean the Customer or the User? Those are different things."

Scenario-based edge-case testing — When domain relationships are discussed, stress-test with concrete scenarios that probe boundaries between concepts.

4. Update docs inline

CONTEXT.md — When a term is resolved, update it immediately. Don't batch updates.

File structure for single-context repos:

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       └── 0001-decision-name.md

For monorepos with CONTEXT-MAP.md at root, each context has its own CONTEXT.md and docs/adr/.

Create files lazily — only when you have something to write.

ADRs — Only create when all three are true:

Hard to reverse (meaningful cost to change later)
Surprising without context (future reader would wonder "why?")
Result of a real trade-off (genuine alternatives existed)

If any condition is missing, skip the ADR.

Cross-reference with code

When the user states how something works, verify the code agrees. Surface contradictions:

"Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"

File formats

CONTEXT.md: domain terminology meaningful to domain experts (no implementation details)
ADR format: title, status, context, decision, consequences

Instructions

Identify the task trigger and expected output.
Follow the workflow steps in this skill from top to bottom.
Validate outputs before moving to the next step.
Capture blockers and fallback path if any step fails.

Examples

Example: Apply this skill to a small scope first, then scale to full scope after validation passes.

Best practices

Keep outputs deterministic and auditable.
Prefer small reversible changes over broad risky edits.
Record assumptions explicitly.

References

Project standards: .agent-skills/skill-standardization/SKILL.md
Validator script: .agent-skills/skill-standardization/scripts/validate_skill.sh

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/akillness-jeo-skills-grill-with-docs/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

akillness-jeo-skills-grill-with-docs.ocm.jsonjson

{
  "ocm": "1",
  "id": "akillness-jeo-skills-grill-with-docs",
  "kind": "skill",
  "name": "grill-with-docs",
  "description": "Stress-test plans against project domain model, sharpen terminology, update CONTEXT.md and ADRs inline",
  "publisher": "akillness",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "design-review",
      "architecture",
      "domain-model",
      "documentation",
      "adr",
      "context-map",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Stress-test plans against project domain model, sharpen terminology, update CONTEXT.md and ADRs inline"
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/akillness/jeo-skills",
      "path": ".agent-skills/grill-with-docs/SKILL.md",
      "ref": "HEAD",
      "url": "https://www.skills.sh/akillness/jeo-skills/grill-with-docs",
      "key": "akillness/jeo-skills/.agent-skills/grill-with-docs/SKILL.md"
    },
    "compatibility": "Works best in codebases with CONTEXT.md and docs/adr/ documentation. Creates these files lazily if absent. Pairs with improve-codebase-architecture for architectural work and triage for issue preparat",
    "allowed_tools": [
      "Read",
      "Grep",
      "Glob",
      "Bash",
      "Write",
      "Edit"
    ]
  },
  "instructions": "# Grill With Docs\n\nA grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation inline as decisions crystallize.\n\n## When to use this skill\n\n- Validating architectural plans against a project's domain language\n- Stress-testing designs before implementation\n- Updating CONTEXT.md terminology as new concepts emerge\n- Preparing issues for implementation (pairs with `triage`)\n\n## When not to use this skill\n\n- Finding refactoring opportunities → use `improve-codebase-architecture`\n- Writing implementation tickets → use `to-issues`\n- ",
  "cost": {
    "context_tokens": 859
  }
}

Fetch it by URL: GET /api/v1/registry/akillness-jeo-skills-grill-with-docs/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.