import

Files (1)

• SKILL.md

SKILL.md (first lines)

# Flywheel import — the cut and the conversions

You are a design session charged with an import batch. The governing
promise is the intent's `decisions/onboarding-promise.md`; this skill
is the process shape it writes down once. The cut and every
conversion are judgment every time — this skill structures that
judgment and replaces none of it.

**An import runs inside the corpus org's own flywheel.** The org that
owns the corpus runs the import against its own design repo, tracker,
and state — corpus content never crosses into another org's repos.
What is shared across orgs is this skill, nothing corpus-specific.

**An import is a move, not a copy.** As each artifact is processed it
is removed from the source repo, and the untouched original is stored
at `$XDG_STATE_HOME/flywheel/<org>/imports/<repo>/originals/<path>`
(default `~/.local/state`), so nothing is lost and nothing sits
converted in two places. The shrinking source repo is the visible
progress; the ledger (step 4) is its committed record.

## The two inputs

An import reads **two** trees, always:

- the **corpus** — the source repo, pinned at a sha your report names;
- the **destination books** — pinned the same way.

No settled-history row is assignable until the books are read. Where
the destination books do not exist yet, say so in the cut's header;
the lane is then assignable from the corpus alone.

## Step 1 — Inventory

- Enumerate with `git ls-files`, **never `find`** — a filesystem walk
  inflates the corpus with vendored trees (measured: 2.3×).
- Every tracked file, not a file-type guess: classify by type and
  **report what you set aside** rather than silently excluding it — a
  corpus has kept its import-state in a `.json` nobody would have
  listed.
- Date everything: `git log -1 --format=%ad -- <path>` per file. Date
  clusters map onto lanes; a derived artifact older than its source
  is stale by construction.
- **Find the corpus's own progress ledger before reading anything
  long**: a phasing section, a roadmap page, a findings sink, a state
  file. Do not go looking for the file the operator named — the
  operator's pointer is seed evidence, and a seed that misses is not
  a corpus defect. Where renderings of the ledger disagree, the one
  the corpus names as its source of truth wins, and the disagreement
  is triage evidence.
- Pin corpus sha and books sha in the cut's header.

## Step 2 — The cut

A durable triage report, committed in the intent's change directory.
Granularity: file-or-section, **and below a section wherever a
trailing subsection changes lane** — a settled block's "writeback
hook" / "still open" / "what has to change" tail is live work by
default; two rows for one section is normal.

Read in this order:

1. **Harvest the corpus's own lane markers first** — status lines,
   `(settled)` headers, DONE stamps — and spend the reading budget on
   the unmarked regions.
2. **Confirm markers against the corpus's named source of truth
   before laning.** A marker states the author's intent at writing,
   not current truth.

Each row: artifact/span, lane, one-line reason, checkable pointer.
The lanes:

| lane | meaning | conversion consequence |
| --- | --- | --- |
| `discard` | the row is the record that it was seen | none beyond the originals folder |
| `withhold` | seen, must not be carried forward | none; row records the **class** (account id, network id, credential path, IAM grant) and **quotes nothing** — never an excerpt, never a line range that invites a look; the original exists only in the state folder |
| `settled-history` | a concluded decision, design, or finding | convert per the two qualifiers below |
| `live-work` | work still to do | routed by kind — design-level direction and forward intent go **into the design books** (bolt planning carves bolt unit plans from the books on demand); only already-concrete, actionable work becomes queued tracker items, all at Backlog |

`settled-history` carries two qualifiers, both mandatory:

- **coverage**: `unwritten` (convert) or `already-in-books` (record
  provenance, cite the chapter — converting duplicates a chapter that
  exists). The corpus may assert the opposite of the truth here; only
  the books settle it.
- **currency**: `current` (eligible to update the books) or
  `superseded` (a historical record with a dated caveat, **never** a
  books update). The corpus's own disclaimers and its date clusters
  are the evidence.

Any row may carry the **`sole-holder` flag**: the corpus is the only
copy. The flag's consequence is preservation — the artifact is
**adopted whole** into the import's archive before the corpus can be
retired — which is a separate act from conversion, owed even when
nobody has to read the thing today.

*Restated elsewhere* is a claim you check, never infer from the
presence of a summary. Two steps, neither substituting for the other:

1. **The restatement check (filter):** grep the live document for
   references to the artifact and read whether they carry the content
   or merely name it. A pointer is not a restatement.
2. **The read (verdict):** what the filter passes still needs a
   reader — unrestated material can settle nothing and be discard
   anyway.

**Form check:** an artifact whose form its supposed source cannot
express — hand-authored SVG in an HTML report, against a markdown
source — is a sole holder by construction and no grep will find it.
Ask what form each artifact carries; adopt diagrams whole rather than
converting them.

**Operating documentation** — how to run the thing as it stands — is
none of the lanes. Ask the operator **once per corpus**: if the repo
lives on, it is out of the import's scope entirely; if the repo is
being imported out of existence, it is removed with everything else
and its originals kept in the state folder — recoverable, never
converted into records it does not contain.

**A lane is a disposition for the corpus, never a judgment about

From agentplot/flywheel, MIT.

More from agentplot/flywheel