packages/std/evals/system-improver.prose.md

name: system-improver kind: function version: 0.15.0

System Improver

Given an inspection report and the inspected system's source, analyze the system for improvement opportunities and produce ranked proposals with diffs. This function operates on OpenProse contracts (*.prose.md source files) and understands the full contract surface: requires, maintains, errors, invariants, strategies, environment, and shapes.

Parameters

inspection: run — a completed inspector run whose output identifies issues with a system
source-path: path to the system's source directory containing *.prose.md files

Returns

improvements: ranked list of improvement opportunities, each containing:
- rank: priority position (1 = highest impact)
- category: one of "contract" (maintains/requires/parameters/returns quality), "strategy" (missing or vague strategies), "shape" (delegation boundary violations), "structure" (sub-unit decomposition issues), "error-handling" (missing error declarations or conditional returns), "efficiency" (unnecessary sub-units or missing parallelization)
- description: what the problem is
- evidence: specific reference to inspection findings and system source
- diff: proposed change as a unified diff against the source file
- risk: "low" (safe refactor), "medium" (changes contract surface), or "high" (changes system behavior)
if no improvements found: an empty list with an explanation of why the system is sound
every returned improvement's evidence cites both a specific inspection finding and a specific source location, and every diff is minimal (one concern per diff, never a wholesale rewrite), with contract-violation and missing-error-handling improvements ranked above efficiency improvements

Errors

source-not-found: the source-path does not contain valid OpenProse system files
inspection-invalid: the inspection run output is not a valid inspector report

Strategies

when analyzing contracts: check that every maintains clause is specific enough to evaluate — vague maintains like "a good report" are improvement targets
when analyzing strategies: check that strategies cover the system's known failure modes — if the inspection shows failures, the system should have strategies to handle them
when analyzing shapes: verify that services with shape.delegates actually delegate (not collapse), and services with shape.prohibited do not violate boundaries
when proposing diffs: make minimal changes — one concern per diff. Never rewrite a system wholesale.
when ranking: prioritize contract violations and missing error handling over efficiency improvements

Execution

let located = call locator
  source-path: source-path
  inspection: inspection

let analysis = call analyst
  root-source: located.root-source
  service-sources: located.service-sources
  inspection-output: located.inspection-output

let result = call implementer
  analysis: analysis.analysis
  root-source: located.root-source
  service-sources: located.service-sources

return { improvements: result.improvements }

locator

Find and read the system source files. Validate that the source path contains a valid OpenProse system.

Parameters

source-path: path to the system's source directory
inspection: the inspection run binding

Returns

root-source: the root source file content (the root *.prose.md contract file)
service-sources: map of service name to file content for each service in the system
inspection-output: the inspection report extracted from the inspection run's bindings

Errors

source-not-found: source-path does not exist or contains no root contract source file
inspection-invalid: cannot find or parse the inspection output from the run

Strategies

look for the root source by scanning *.prose.md files for the root contract in frontmatter
resolve service files relative to the root source file's directory
read the inspection output from the run's bindings directory

analyst

Examine the system source against the inspection findings. Identify every improvement opportunity with evidence from both sources.

Parameters

root-source: root source content from locator
service-sources: service file contents from locator
inspection-output: inspection report from locator

Returns

analysis: list of improvement opportunities, each with category, description, evidence, affected file, and estimated impact
each opportunity has: a reference to the specific inspection finding that motivates it AND a reference to the specific source location that needs changing

Strategies

check contract quality: are maintains clauses specific and evaluable? are requires clauses typed clearly? are error conditions declared for plausible failure modes?
check strategy coverage: does every service that could fail have relevant strategies? do strategies reference concrete conditions, not vague heuristics?
check shape consistency: do shape.self lists match what the contract actually does? do shape.delegates match the call targets in ### Execution? are shape.prohibited entries respected in the contract body?
check structural efficiency: are independent sub-units wired for parallel execution? are there sub-units that could be merged or split?
check error handling: does the system have conditional returns for each declared error? are degradation paths specified?
when the inspection shows a "pass" verdict: still look for improvements — a passing system can still have quality issues
when the inspection shows a "fail" verdict: prioritize the root cause of failure above all other improvements

implementer

Transform analysis results into concrete diffs. Each diff must be minimal, correct, and independently applicable.

Parameters

analysis: improvement opportunities from analyst
root-source: root source content from locator
service-sources: service file contents from locator

Returns

improvements: the final ranked list matching the function's top-level returns schema, with diffs generated for each opportunity

Strategies

when generating diffs: use unified diff format with enough context lines (3+) to unambiguously locate the change
when multiple improvements affect the same file: ensure diffs are independently applicable (no conflicts if applied in isolation)
when a change affects the contract surface (requires/maintains): flag as "medium" risk since downstream consumers may depend on the current contract
when a change only affects strategies or internal service content: flag as "low" risk
when proposing new services or removing existing ones: flag as "high" risk