agentleFS
netanelavrnetanelavr/dotcursor/skills/kit-challenge-design/SKILL.md

kit-challenge-design

Skill6 starsChanged 27 days agoMITView on GitHub

Stress-test a plan or design against domain language, docs, and code. Ask hard questions one at a time. Update CONTEXT.md and ADRs as decisions crystallize. Use when you already have a draft plan or spec and want to find gaps before implementation.

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. About 0 are common, 15 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈15

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this when you already have a plan, spec, or design doc and want to find gaps, contradictions, and fuzzy language before implementation.

    line 13
  2. Distinctive:

    Do not use this when:

    line 17
  3. Distinctive:

    If omitted, use the current conversation topic or ask what to review.

    line 29
  4. Distinctive:

    Before asking anything, explore the project.

    line 33
  5. Very specific:

    Only a root CONTEXT.md exists → single context

    line 67
  6. Distinctive:

    When multiple contexts exist, infer which one the current topic relates to.

    line 70
  7. Very specific:

    Create CONTEXT.md or docs/adr/ lazily — only when you have something to write.

    line 94
  8. Distinctive:

    One question at a time: Wait for the user's answer before the next question.

    line 102
  9. Distinctive:

    Explore, don't ask: If the answer is in the codebase or docs, look it up and report what you found.

    line 103
  10. Distinctive:

    Diagnosis changed → regenerate, don't patch: If the hypothesis changes mid-review, discard the plan and write a new one from the new …

    line 140
  11. Distinctive:

    Do not batch glossary or ADR updates until the end.

    line 144
  12. Distinctive:

    Only project-specific domain terms.

    line 175
  13. Distinctive:

    Only offer an ADR when all three are true:

    line 180
  14. Distinctive:

    If any condition fails, skip the ADR.

    line 186
  15. Distinctive:

    When the reviewed file is a plan or spec, offer to patch it with resolved decisions, clarified terms, and scoped non-goals.

    line 218
  16. Distinctive:

    After each answered question, briefly note:

    line 222
  17. Distinctive:

    When the user signals the review is done (or all branches are resolved), post a closing summary:

    line 228

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “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

Challenge Design

Stress-test a plan or design against the project's domain language, existing docs, and code. Ask hard questions one at a time. Capture resolved terms in CONTEXT.md and hard-to-reverse decisions in docs/adr/ as they crystallize.

When to use

Use this when you already have a plan, spec, or design doc and want to find gaps, contradictions, and fuzzy language before implementation.

A plan to fix a bug or failing test counts as a draft. Grill it here before any code edit.

Do not use this when:

  • The idea is still fuzzy and no draft exists yet. Hand off to kit-plan (align concept + decision log; do not auto-write a PRD). Run this skill only after there is a draft to grill.
  • You want to review code diffs for bugs or security. That is kit-review, not domain design grilling.
  • You want a living log of tried paths, rejects, and landmines for one feature. That is kit-decisions. ADRs here stay sparse.

Input

kit-challenge-design [PATH_OR_TOPIC] — optional.

  • PATH: design doc, plan, or spec
  • TOPIC: short description of the existing draft in chat (still needs a draft — fuzzy with nothing written → kit-plan)
  • If omitted, use the current conversation topic or ask what to review.

0. Load domain context

Before asking anything, explore the project.

Documentation layout

Single context (most repos):

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       └── NNNN-{slug}.md
└── {source}/

Multiple contexts (when CONTEXT-MAP.md exists at the root):

/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                    ← system-wide decisions
└── {source}/
    ├── {context-a}/
    │   ├── CONTEXT.md
    │   └── docs/adr/           ← context-specific decisions
    └── {context-b}/
        ├── CONTEXT.md
        └── docs/adr/

Infer which structure applies:

  • CONTEXT-MAP.md exists → read it to find contexts and their relationships
  • Only a root CONTEXT.md exists → single context
  • Neither exists → create a root CONTEXT.md lazily when the first term is resolved

When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

CONTEXT-MAP.md format:

# Context Map

## Contexts

- [{Context A}]({path}/CONTEXT.md) — {one-line description}
- [{Context B}]({path}/CONTEXT.md) — {one-line description}

## Relationships

- **{A} → {B}**: {how they interact}

What to read

  1. Glossary — CONTEXT.md (root or per-context via CONTEXT-MAP.md)
  2. Decisions — docs/adr/*.md and context-specific docs/adr/ if present
  3. Plans and specs — design docs, plans folders, and any linked wiki pages referenced in doc frontmatter
  4. Code — search the codebase to verify how things work today; check architecture docs and module boundaries when the design crosses components

Create CONTEXT.md or docs/adr/ lazily — only when you have something to write.

1. Grilling session

Interview relentlessly until you and the user share a clear understanding. Walk each branch of the design tree. Resolve dependencies between decisions one at a time.

Rules

  • One question at a time. Wait for the user's answer before the next question.
  • Explore, don't ask. If the answer is in the codebase or docs, look it up and report what you found.
  • Recommend an answer with every question. State your pick and why.
  • No implementation during the session unless the user explicitly asks to update docs (see section 2).

Challenge the plan

TriggerAction
Term conflicts with CONTEXT.mdCall it out immediately. Quote the existing definition and ask which meaning applies.
Vague or overloaded termPropose a precise canonical term. Ask whether it maps to an existing concept or needs a new glossary entry.
Relationship between conceptsInvent a concrete scenario that probes an edge case. Force a clear boundary between concepts.
User states how something worksCross-check the code. If it contradicts the plan, surface the mismatch and ask which is authoritative.
Missing non-goals or scopeAsk what is explicitly out of scope for this change.
Plan fixes a bug / failing testRun the Repair-plan attack (below) first: mechanism over intent, every step tested against the failing assertion.

Question order (adapt to the design)

Work through branches in dependency order. Typical sequence:

  1. Problem and success — What user or system outcome changes? How will we know it worked?
  2. Scope and non-goals — What is in v1? What is explicitly deferred?
  3. Domain terms — Name the nouns and verbs. Resolve collisions with existing language.
  4. Boundaries — Which component or context owns what? What crosses a boundary and how?
  5. Data and contracts — Inputs, outputs, persistence, events, API shapes.
  6. Failure and edge cases — Timeouts, retries, partial success, auth, idempotency.
  7. Observability and ops — Logging, metrics, rollout, rollback.
  8. Trade-offs — Alternatives considered; why this path over others.

Skip branches that do not apply. Go deeper where the design is fuzzy or risky.

Repair-plan attack (before editing)

Applies when the draft is a plan to fix a bug or a failing test. A wrong idea planted at the plan stage costs far more than the same wrong idea at the hypothesis stage. Kill it while critiquing the plan, before any edit.

  • Mechanism, not intent. Critique HOW the fix works — state ownership, update order, error handling — not whether the goal sounds right. A plan can sound right and still be mechanically wrong.
  • Attack against the failing test. Walk each plan step against the exact failing assertion/output. Any step that cannot change the observed failure is suspect; name which steps survive and why.
  • Hypothesis and plan stay separate. The diagnosis (why it fails) and the repair plan (what to change) are two artifacts. The plan must not silently absorb or rewrite the hypothesis.
  • Diagnosis changed → regenerate, don't patch. If the hypothesis changes mid-review, discard the plan and write a new one from the new diagnosis. Patching an old plan onto a new cause is how poisoned plans survive.

2. Update documentation inline

Do not batch glossary or ADR updates until the end. Capture decisions as they land.

CONTEXT.md (glossary only)

  • Single context: root CONTEXT.md
  • Multiple contexts: the CONTEXT.md for the relevant bounded context (use CONTEXT-MAP.md to pick)

CONTEXT.md is a glossary and nothing else. No implementation details. No scratch notes. No specs.

Format:

# {Context Name}

{One or two sentences: what this context is and why it exists.}

## Language

**{Canonical term}**:
{One or two sentence definition: what it IS.}
_Avoid_: {alternative terms to not use}

**{Another term}**:
{Definition.}
_Avoid_: {alternatives}

Rules:

  • Be opinionated: pick one canonical term; list alternatives under _Avoid_.
  • Definitions are one or two sentences: what it IS, not what it does.
  • Only project-specific domain terms. Before adding a term, ask: is this unique to this context, or a general programming concept? Only the former belongs.
  • Group under subheadings when natural clusters emerge. A flat list is fine when all terms belong to one area.

ADRs (sparingly)

Only offer an ADR when all three are true:

  1. Hard to reverse — meaningful cost to change later
  2. Surprising without context — a future reader will look at the code and wonder "why did they do it this way?"
  3. Real trade-off — genuine alternatives existed and you picked one for specific reasons

If any condition fails, skip the ADR. Easy-to-reverse decisions get reversed, not documented. Obvious choices need no record.

What qualifies:

  • Architectural shape
  • Integration patterns between contexts or services
  • Technology choices with lock-in — not every library
  • Boundary and scope decisions about data ownership
  • Deliberate deviations from the obvious path
  • Constraints not visible in code
  • Rejected alternatives when the rejection is non-obvious

Location: docs/adr/NNNN-slug.md. Scan docs/adr/ for the highest existing number and increment by one. Create the directory lazily when the first ADR is needed.

Format:

# {Short title of the decision}

{1-3 sentences: context, decision, and why.}

That can be a single paragraph. The value is recording that a decision was made and why.

Optional sections — only when they add genuine value:

  • Status frontmatter (proposed | accepted | deprecated | superseded by ADR-NNNN)
  • Considered Options — when rejected alternatives are worth remembering
  • Consequences — when non-obvious downstream effects need to be called out

Design doc updates

When the reviewed file is a plan or spec, offer to patch it with resolved decisions, clarified terms, and scoped non-goals. Do not rewrite the whole doc. Minimal diffs for what changed during the review.

3. Session output

After each answered question, briefly note:

  • Decision made (or still open)
  • Doc updated (CONTEXT term, ADR offered/created, design doc patch)
  • Code contradiction found (if any)

When the user signals the review is done (or all branches are resolved), post a closing summary:

## Challenge design summary

**Reviewed:** {path or topic}

### Resolved
- {decision or term} → {outcome}

### Open questions
- {anything still undecided}

### Docs updated
- {file paths created or changed}

### ADRs
- {created or deferred, with reason}

### Code contradictions
- {mismatch and recommended resolution, or "None."}

### Recommended next step
- {next action}

Skip

  • Writing implementation code or scaffolding during the review
  • Creating ADRs for obvious or easily reversed choices
  • Filling CONTEXT.md with generic programming terms
  • Batch-updating docs at the end instead of inline as terms resolve
  • Reviewing code diffs for bugs — that is outside the scope of this command

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.