Walsworth-Group/physkit / skills/frame-problem
frame-problem
VerifiedFrame a physics problem before modeling, simulating, deriving, or fitting: physics inventory, verification plan, decomposition into checked steps.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.7 KB |
| assets/framing_template.md | markdown | 2.5 KB |
SKILL.md
View on GitHub---
name: frame-problem
description: >-
Frame a physics problem before modeling, simulating, deriving, or fitting: physics inventory,
verification plan, decomposition into checked steps.
---
# frame-problem — scope the physics before you do the work
Three classes of error in physical-science work are fixed before any code runs: an effect left out of the
model, a result with no planned check, and a long build whose second step was wrong and was caught at the
ninth. This skill spends a few minutes up front to prevent them. It turns a clear goal into an explicit
**frame**: which physics is in play, how the answer will be checked, and the order the work is built in.
It runs after the goal is clear. That clarification is the always-on CORE stance (state assumptions,
present interpretations, push back, stop when confused), not this skill's job. If the goal is still fuzzy,
resolve that first; framing a misunderstood goal produces a confident wrong plan. Once the goal is clear,
produce the three outputs below, then show them to the user to confirm or correct before executing. The
frame is a hypothesis about the problem, and the user is the cheapest check on it.
For a trivial single-step question, answer it directly. Frame every problem that has more than one moving
part or any way to be quietly wrong.
---
## 1 · Physics inventory — what's in, what's out, and *why*
List the physical effects that could matter to the answer, and tag each one. Every omission is then
deliberate and auditable rather than forgotten.
| tag | meaning |
|---|---|
| **accounted-for** | included in the model |
| **negligible-by-scale** | left out because an estimate shows it's small *here* — give the estimate (a ratio, an order of magnitude) |
| **out-of-scope** | real but outside what this work is answering — say so |
| **deferred** | will matter, but added in a later step — note where |
| **unknown** | might matter; you can't yet tell — flag it as a risk |
Rules that make the inventory honest:
- Justify every "not accounted-for." "Negligible" without a number is a guess. Use
`dimensional-analysis` to estimate the size of an effect and to find the dimensionless groups that say
which terms dominate; that is how a term is shown to be negligible in this regime.
- Bound the answer a priori. Before building anything, compute the ceiling, floor, and order of magnitude
the result must fall within, from units, limits, and known system properties (`dimensional-analysis`). A
later result outside this envelope is a bug or a discovery; decide which before acting on it.
- State the domain of validity and the key assumptions the model rests on.
- Anchor load-bearing facts, not only effects. A system parameter or convention taken from a paper,
leftover code, or memory is a description of the system, not the system. Pin each one to the
highest-authority artifact you can parse or run, and tag its provenance (the ladder and tags are in `verify` §5b). An
unpinned load-bearing fact is a risk, like an unjustified "negligible."
- Derive implied counts from a named structure; do not take the given number on its own. When the problem
references a named structure class (a lattice, a symmetry group, a periodic or composite geometry), that
name carries an implicit multiplicity or count. Derive it from the structure's definition and cross-check
it against any count given in the framing. A mismatch is load-bearing: an implicit-count error changes
handedness, degeneracy, or scale in everything downstream, and it throws no error, only a
plausible-looking wrong answer.
- Keep the inventory living. A persistent gap between model and data, after the work checks out, points at
a parked or missing effect here (model-form error), or at a bug in the FROZEN reference code or forward
model, where a sign or convention error upstream presents as missing physics. Re-verify that
infrastructure; do not only add terms. Update the inventory as understanding changes; in a campaign it
graduates into the project overview's (`PROJECT.md`) §Standing constraints.
### The predictive framework — the model you predict *with* (and revise)
The inventory records which effects are in play. The **predictive framework** is the model that ties them
into predictions: the model an expert physicist reasons from. Name it explicitly.
- The mechanism, the key variables, and their relationships, at a complexity matched to the problem: the
minimally-sufficient level, and why this level and not more. In a laser-cooling model that is photon
versus atom momentum, the light-scattering conversion between them, and the scattering rate's dependence
on light frequency and Doppler shift.
- The thought-experiments it licenses: if X changes, the framework predicts Y. These are the a-priori
predictions and a source of candidate solutions. Run them before running code.
- Enumerate candidate approaches before committing to one. The thought-experiments usually suggest several
possible levers or solutions. Write a short divergent list with a one-line pro and con for each, and
choose among them deliberately rather than taking the first idea that came to mind.
- Keep it revisable, and log the revisions. When data disagrees with the framework's prediction (a
structured residual, an out-of-envelope result), decide whether the anomaly fits the framework's stated
domain or the framework itself must change, then record what changed and why. The revised laser-cooling
model adds the AC Stark shift and its spatial variation across the beam. In a campaign this revision log
lives in `PROJECT.md`, in its "Updates from discoveries" section.
## 2 · Verification plan — how you'll know the answer is right (decided up front)
Decide how the answer will be checked before computing it, not after. A check designed before the result
exists is independent of the result; a check chosen once a number is in hand is selected by that number.
Draft the plan as a short list of concrete checks, each one committed to being run.
Draw from the following. Not all apply to every problem.
- **Analytic / closed-form limits** the result must reproduce (a known special case, a small/large-parameter
limit, a symmetry).
- **Conservation and symmetry invariants** that must hold (energy/mass/charge; the symmetries of the setup).
- **Dimensional / units sanity.** Run it first; it is the cheapest check available (`dimensional-analysis`).
- **Numerical convergence.** If anything is discretized, state the plan to refine timestep, grid, or
tolerance until the answer stops moving, and to separate numerical error from model error.
- **Independent, mechanism-diverse parity.** A second method, an independent computation, or a certifying
solver that must agree. Warrant rests on an independent checker, not on a prose argument.
- **Validation against data.** Comparison to measurement or an established benchmark, with uncertainty on
both sides, on held-out or independent data. Mark it as validation ("solving the right equations"),
distinct from verification ("solving the equations right"). Verify before you validate, and calibration
is not validation.
- **Application-specific checks and known gotchas.** The field-standard comparisons, known artifacts, and
the checks everyone in the subfield runs on this class of problem. Record them at framing time; they are
easy to omit later and expensive to miss. In a campaign they land in `campaign.md` §Verification
and feed `correctness-suite`, which promotes each check to a standing
regression gate.
For each check, name the arbiter: a coded gate, or the model's judgment. Prefer a coded gate that emits the
verdict; the model explains and acts on that verdict but does not decide it. Reserve model judgment for
what cannot be coded, such as a physical-plausibility call, and state why.
The plan is the input to the rest of the pipeline: `correctness-suite` executes the checkable ones, `verify`
adversarially checks the resulting claims, and `simulation-design` turns this into a sim's full V&V&UQ plan.
Record the reason for any non-obvious check (`record-decision`).
## 3 · Decomposition — small steps, verified where it matters
Break the work into small sub-steps that can be done one at a time. For each step, note what it produces,
what it depends on, and, for the steps that matter, its check.
- Verify between steps in proportion to risk, not after every trivial step. Put a checkpoint where a later
step depends on this one, or where an error would compound. A wrong foundation found at step two is
cheap; found at step nine it is a rebuild.
- Flag the crux sub-steps and set an acceptable-uncertainty bar. Name the sub-steps that are hardest or
most uncertain, where the plan is most likely wrong, and decide how certain the result must be to proceed
past each one. That threshold is the acceptable-uncertainty bar for that stage. Risk concentrates at
those steps; put the checkpoints and the early de-risking effort there.
- Build the simplest sufficient version first, then add the deferred effects from the inventory one at a
time. Each addition is a step, and ideally each is independently checkable. Validating a simpler subcase
first usually yields a stronger, better-validated final result.
- Name what each step changes, so its effect stays attributable. Moving several together is legitimate
when the cost is justified (coupled levers, a screen, an interaction test); state which moved, and expect `verify`
to grade the attribution spent.
How much to persist (do not create a document for a small job):
- **Trivial / short:** keep the steps in your head or a scratch list and do them.
- **General session, non-trivial:** a maintained checklist (steps, status, which were checked). It
graduates into a campaign if the work grows into one.
- **Campaign:** the decomposition becomes the opening `results/JOURNAL.md` — the **NEXT:** pointer and
§What to try next and why, each step with its rationale (how it serves the goal). `new-campaign` owns
that seeding; `frame-problem` feeds it.
---
## Surface the frame, then execute
Show the user the three outputs together (inventory, verification plan, step plan) and invite correction.
This is the cheapest point at which to catch a missing effect, a check that will not discriminate, or a
step order that buries risk. Then execute the steps, running each planned check at its checkpoint.
## Persist a framing artifact (when the work is non-trivial)
For anything beyond a quick question, write the frame to a durable **framing artifact** (template:
`assets/framing_template.md`) so it survives the session and seeds what comes next. Its content graduates:
the inventory to `PROJECT.md` §Standing constraints, the goal to `campaign.md` and the steps
to the JOURNAL (NEXT + What to try next and why) in a campaign, the
verification plan to the verification gate. Keep one artifact, and update it as the frame changes.
## Composition & boundaries
- `new-campaign` composes this skill and confirms rather than re-asking: `frame-problem` owns the physics
scoping and writes the artifact; `new-campaign` reads it back and adds campaign-only topics (metric,
levers, data, compute, archetype). Within a session this is shared context; across sessions the persisted
artifact carries it. Do not run a second interview.
- `simulation-design` starts from this skill's inventory and turns the verification plan into a full V&V&UQ
plan before any simulation code is written.
- `dimensional-analysis` does the bounding and dominant-term work in steps 1–2.
- `docs/reference/coordinate-frames.md` — for a geometry-heavy problem, declare each coordinate frame
(name, origin, axes, handedness) in the inventory, and pin how every transpose, handedness, and sign
ambiguity is broken, using an independent reference. `verify` runs the frame-consistency checklist
downstream.
- `verify` and `correctness-suite` consume the verification plan downstream.
- `attribute-mechanism` consumes this skill's effect inventory as its candidate-mechanism list when an
observed signature later needs its physical cause established.
## Worked mini-example (estimate, then frame)
*Goal (already clarified): predict the diffusion-limited current at a microelectrode for a redox couple.*
- **Inventory:** bulk diffusion **accounted-for**; spherical/edge geometry **accounted-for**; migration
**negligible-by-scale** (excess supporting electrolyte → transference number ≪ 1, give the ratio);
natural convection **out-of-scope** (quiescent, short timescale; state the timescale); double-layer
charging **deferred** (matters only at early times; added in step 3); adsorption **unknown** (flag).
- **A-priori bound:** steady-state $i \sim n F D c\, r$ (with an $O(1)$ geometry-dependent prefactor — 4
for a microdisk of radius $r$) sets the order of magnitude; the answer must land within a small factor
of it (`dimensional-analysis`).
- **Verification plan:** recover the planar Cottrell limit as $r\to\infty$ (analytic limit); check the
steady-state scaling with $r$ and $c$; converge the mesh near the electrode edge; compare to the
published microdisk result (validation, independent data).
- **Decomposition:** (1) steady-state analytic estimate [check: units + the bound]; (2) numerical
steady-state solve [check: matches (1) within mesh error, convergence demonstrated]; (3) add transient +
double-layer [check: recovers Cottrell at short time]. Verify after (2) — step (3) builds on it.
## Before you call the frame done — checklist
- [ ] Every effect that could matter is listed and tagged; each "not accounted-for" has a reason (a number where it's "negligible").
- [ ] The answer is bounded a priori (ceiling / floor / order of magnitude).
- [ ] The **predictive framework** is named (mechanism, variables, and relationships, at a complexity justified for the problem), the thought-experiments it licenses are stated, and it is set up to be revised, with a logged reason, when data disagrees.
- [ ] Candidate approaches enumerated (divergent, pro/con) before committing; the crux/highest-uncertainty sub-steps flagged with an acceptable-uncertainty bar.
- [ ] Key assumptions and the domain of validity are stated.
- [ ] The verification plan is concrete and decided before computing; verification vs validation marked; calibration ≠ validation noted where relevant.
- [ ] Application-specific checks / known gotchas captured.
- [ ] The work is decomposed into steps with checkpoints where risk compounds (not everywhere).
- [ ] The three outputs were shown to the user for confirmation.
- [ ] A framing artifact is written if the work is non-trivial (else intentionally skipped).
## Bundled assets
- `assets/framing_template.md` — the durable framing artifact: goal recap · physics inventory table ·
verification plan · decomposition with checkpoints.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |