Collection-aware full improvement pass

Goal

Determine how Commonplace should improve existing prose outside kb/notes/ without imposing a theory-note contract on artifacts that serve a different function. Any resulting procedure should respect the target collection, artifact type, local framing, quality goal, unresolved choices, and decision authority before it selects review methods or applies edits.

The workshop must also decide whether this should be one routed full-improvement procedure, a small family of collection- or artifact-specific procedures, or a narrower note-only procedure with report-only support elsewhere. Starting the workshop does not select among those designs.

Why this workshop exists

run-full-improvement-pass-on-note.md grew out of the agent-note-improvement workshop and was calibrated on theoretical library notes. Its method order, contribution packet, claim critique, premise attack, title reframe, and closing cycle are correspondingly note-shaped.

A later run applied it to a proposed experiment design in a live workshop. The pass improved organization, terminology, and the visibility of the comparison. It also converted implicit workshop text to a note, treated the design alternately as a claim and a procedure, and turned several reviewer-supplied experimental choices into the artifact's own prescriptions. The result was coherent on its new terms, but the closing checks did not establish that those terms were authorized by the workshop. Case 01 records the evidence and keeps the design response open.

This is not evidence that the current pass is defective for the theoretical notes it was built to improve. It is evidence that successful note editing does not by itself establish cross-collection method fit.

Question

What applicability, review-routing, synthesis, mutation, and closing contracts let a full improvement pass advance an artifact according to its own collection and function rather than making every target resemble a theoretical claim note?

Starting hypothesis: artifact function is more legible in theory

The kb/notes/ contract makes the reason for an artifact's existence relatively easy to infer. A theory note normally advances a claim, explains a mechanism, or defines a concept, and its title, type, and local contract further constrain that contribution. The full pass can therefore reconstruct a central commitment with a fairly strong prior about what kind of improvement would still serve the artifact.

The workshop layer deliberately removes much of that prior. One file may be evidence, scratch reasoning, a proposal, a decision surface, a handoff, an experiment record, or material awaiting extraction. The collection-wide goal to “move the work forward” does not determine which of those jobs a particular file performs. A local README may narrow the inquiry while still leaving the individual file's role and decision authority implicit.

Hypothesis: safe automatic improvement depends on how legible the artifact's function is, not only on how strong its collection text contract is. When a workshop file's function cannot be recovered confidently from its collection, type, local framing, and text, a note-shaped review suite will tend to supply the missing purpose itself. The resulting edit may be coherent while changing what the artifact is for or deciding questions it was meant only to expose.

This predicts that:

  • independent reviewers will agree more often about the function and permitted edit boundary of theoretical notes than of otherwise comparable workshop files;
  • disagreement about artifact function will correlate with review-mode changes, type conversion, and newly selected commitments; and
  • an explicit function brief will reduce those changes while preserving ordinary structural and readability improvements.

Comparable agreement and commitment preservation without an explicit function brief would weaken the hypothesis. So would a function brief that fails to improve reviewer agreement or edit fidelity. Until worked cases test it, “function must be explicit before mutation” remains a candidate rule rather than a workshop conclusion.

Evaluation boundary

The workshop concerns authored natural-language artifacts that their governing contracts permit an agent to revise. It includes system-definition prose, such as instructions, only if a candidate design accounts for its binding behavioral effects, authority, and appropriate validation.

The workshop may investigate:

  • how a pass determines its governing collection, type, local framing, artifact function, and quality goal;
  • which artifact shapes are eligible for automatic editing, report-only diagnosis, or refusal;
  • how review methods are selected or omitted for claims, descriptions, procedures, designs, workshop records, and other demonstrated shapes;
  • how synthesis distinguishes presentation changes, clarifications, qualifications, and new substantive commitments;
  • which changes require authorial or maintainer authority, including type conversion, promotion, rehoming, disposition, and selection among free parameters;
  • what a packet must record so a later reader can audit both editorial quality and contract fidelity; and
  • how final-byte review should vary when the target is not a theoretical note.

The workshop does not assume that every Markdown artifact should be eligible. Captured sources, generated indexes and reports, code or other symbolic artifacts, and collection contracts themselves stay outside the claimed scope unless a worked case establishes a specific reason and review method for including them. The workflow must not change a collection contract merely to make a target pass.

Evaluation dimensions

A candidate design should be judged separately on:

  1. Applicability: it identifies the binding contract and artifact function before expensive or mutating work.
  2. Method fit: its reviewers ask questions that apply to that artifact rather than translating it into a familiar note shape.
  3. Contract fidelity: the result still serves the local quality goal, role, maintenance semantics, and closure conditions.
  4. Commitment preservation: it does not silently choose free parameters, add claims, change type, or expand authority.
  5. Material improvement: the edit makes the artifact better for its actual use, not merely more note-like or more internally polished.
  6. Auditable restraint: report-only and refusal outcomes remain successful outcomes when mutation is not authorized or the intended contribution is underdetermined.
  7. Closing validity: reassessment tests the resulting artifact against the same governing contract and records residual uncertainty without certifying more than it checked.

These dimensions are deliberately non-collapsible. A fluent final artifact can improve materially while still failing commitment preservation, as Case 01 appears to have done.

Open design decisions

The workshop has not yet chosen:

  • one routed procedure versus separate procedures or adapters;
  • whether the current note pass should remain unchanged, gain an early eligibility guard, or become a specialization of a broader workflow;
  • whether artifact function is declared, inferred, or jointly determined from collection, type, and local framing;
  • the minimum evidence needed to classify a proposed edit as clarification rather than a new commitment;
  • the default mutation policy for workshop artifacts and binding instructions;
  • the packet vocabulary for non-claim contributions and non-library closure conditions; or
  • which existing review methods can be reused unchanged, which need an artifact mode, and which should simply be inapplicable.

These choices should be made from worked cases, not settled in the framing file.

Case bookkeeping

Number cases as case-NN-<slug>.md. Each case should record:

  • the frozen input identity and final output identity;
  • the governing collection and type contracts plus any nearer framing artifact;
  • the artifact's working function, open choices, and relevant decision authority at pass start;
  • what the procedure was allowed to change and what it was not authorized to decide;
  • mechanical execution results separately from editorial quality, semantic change, and contract fidelity;
  • observations separately from diagnoses and design decisions; and
  • whether the case informed, selected, or merely failed to rule out a candidate design.

Use frozen copies or versioned captures when a trial might mutate an artifact. Do not infer authorization to edit a live target merely because the target is in a mutable collection.

What would close this workshop

The workshop closes when it has:

  • decided, from worked comparisons, whether to retain a specialized note pass, introduce routing or adapters, or ship separate procedures;
  • tested every collection contract and artifact function that the selected design claims to support, including at least one held-out case for each supported non-notes collection;
  • defined preflight, method-selection, commitment-preservation, mutation-authority, packet, and closing behavior, including explicit abstention paths;
  • shown that the selected workflow improves its supported cases without unapproved type changes or substantive free-parameter selection;
  • landed the resulting durable instruction, reference, type, gate, or ADR changes with the appropriate validation; and
  • named unsupported artifact classes explicitly rather than implying universal Markdown support.

A negative result can also close the workshop: the current pass may remain intentionally theory-note-specific if broader routing does not improve artifacts reliably enough to justify its complexity. After durable conclusions are extracted, remove this workshop and its entry from kb/work/README.md.

Starting evidence

Complete file listing (generated at build time)