agentleFS
dikamilodikamilo/dx-workflow/skills/dx-frame/SKILL.md

dx-frame

Skill8 starsChanged 4 months agoMITView on GitHub

Interview to settle the problem framing, alternatives, and user cases for a change or effort before planning — writes frame.md. Run again on one of an effort's slices to add that slice's own user cases.

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    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. Very specific:

    If the interview below surfaces a term that clashes with the glossary, is vague/overloaded, or finally gets pinned down, invoke dx-domain …

    line 20
  2. Very specific:

    If change.md's type is refactor (or this is a refactor effort), also invoke dx-references with module-design and frame in its vocabulary — …

    line 28
  3. Distinctive:

    Keep it tight and scannable.

    line 43
  4. Distinctive:

    Stop. Do not chain into another skill.

    line 55

≈ “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

dx-frame

Settle the WHAT before the HOW. Run a deep interview on problem framing and alternatives for a change or effort, then write frame.md in its folder. The interview is the cure for misalignment — a perfect plan on the wrong problem loses the day. This makes the framing half explicit and skippable, so dx-plan can jump straight to solution design.

Guard. Resolve <id> under context/changes/ or context/efforts/. If it is missing, tell the user to run /dx-new first. If the path is under context/archive/, refuse — an archived container is done.

Slice mode. If <id> is a change with effort: <effort-id> set and that effort's frame.md already exists, this run is scoped to user cases only: the four core sections (real problem, who/what it affects, alternatives, out of scope) are already settled at the effort level — don't re-ask or rewrite them. Interview and write only this slice's own ## User cases, additive to the parent's. If the parent effort has no frame.md yet, there is nothing to inherit — fall through to full framing below.

1 — Gather settled context

Read change.md (or effort.md) — note type and, for a change, effort:. Read every existing research/<topic>.md, and diagnosis.md and brainstorm.md if present, as settled context; don't re-ask what research already answered. A brainstorm.md already chose the route and priced the do-nothing — deepen its ## Conclusion & route into a full framing rather than reopening it, and treat its ## Not doing as out of scope already decided. In slice mode, also read the parent effort's frame.md in full, including its ## User cases if present — those flows are already covered. Read any brief the container's ## Notes names under foundation/briefs/ — its tagged claims are sourced evidence, so don't re-interview what one already records; its ## Open questions and ## Collection plan are what is still unsettled, and a brief citing material fetched from outside the repo is read under dx-references topic untrusted-content. Read foundation/glossary.md for naming (a one-line habit — no section). Each artifact is a decision already made.

If the interview below surfaces a term that clashes with the glossary, is vague/overloaded, or finally gets pinned down, invoke dx-domain right then — don't just note it and keep talking.

2 — Interview (invoke dx-references with interview)

One question at a time, each offering a few concrete options with one recommended, walking the decision tree until the framing resolves. If the codebase or a research doc can answer a question, explore instead of asking. Scale the count down by whatever upstream already settled. Stay on the WHAT — the real problem, the alternatives, and (when the work is user-facing) the concrete user cases it must cover — never solution design; that is dx-plan's job. Don't manufacture a reframe: "the initial framing was right" is a valid outcome.

User cases scale by batching, not by one question per flow. Print the candidate list as a table — who, trigger, outcome, source — as plain output before any question, then ask one question (confirm or edit); never ask the user to confirm what they haven't seen. Then spend extra questions only on flows still ambiguous after that. For an effort, keep the list to headline flows that matter for slicing — a sketch, not exhaustive, since slices don't exist yet. In slice mode, propose only this slice's candidate additions — flows the parent's sketch didn't name or under-specified for this slice — never re-list what the parent already settled.

If change.md's type is refactor (or this is a refactor effort), also invoke dx-references with module-design and frame in its vocabulary — deep vs shallow modules, seams, the deletion test.

3 — Write frame.md

Slice mode writes only ## User cases to this change's own frame.md — this slice's additional or refined flows. Don't restate the parent's list or touch its file.

Otherwise, write the full frame in the container's folder (context/changes/<id>/frame.md or context/efforts/<id>/frame.md), capturing:

  • The real problem — one sentence, root not surface.
  • Who / what it affects — the users, systems, or code touched.
  • Alternatives considered — the framings weighed, and why the chosen one wins.
  • Out of scope — what this explicitly does not address.

User cases — an optional fifth section, inserted after "Who / what it affects": include it only when the work is user-facing (a UI flow, an API surface, a CLI command) and has more than one flow worth distinguishing. One line each: who, triggered by what, to reach what outcome; note where each came from (already documented upstream, or discovered in this interview) so a reader knows what was newly settled. Omit the section entirely for internal/structural work (a pure refactor, infra, a schema-only migration) — never write it empty or "N/A".

Keep it tight and scannable. No solution phases, no file changes — that is planning.

Done when

Slice mode: this change's frame.md exists with ## User cases. Otherwise: frame.md exists with the four core sections above, plus ## User cases when it applies. Either way, the container's updated: <today> is set. Then print and stop:

Frame written: context/{changes|efforts}/<id>/frame.md
Next: /dx-plan <id>       (for a change)
  or: /dx-roadmap <id>    (for an effort)

Stop. Do not chain into another skill.

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.