# Evolve Note Workflow

> Experimentally improve a traceable note-generation workflow through bounded A/B evaluation.

- Skill: `jm-frank/evolve-note-workflow` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add jm-frank/evolve-note-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jm-frank/evolve-note-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: JM-FRANK (https://skillmd.com/u/jm-frank)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jm-frank/evolve-note-workflow

---


# Evolve Note Workflow

## Scope And Loading

Change note-generation judgment or style through a reproducible historical experiment. Do not generate the next daily note or change deterministic extractors, OCR, converters, hashing, chunking, indexing, or validators here.

Resolve an explicit `series/type` or `repository` scope from current filesystem evidence on every invocation. Read the active generation skill and the owning skill's JSON contract to interpret eligible run evidence; do not obtain paths, state, counters, or schedules from another skill.

## Preconditions And Git Gate

Require explicit authorization before using isolated generator or reviewer agents.

At every invocation:

1. Resolve the repository root from the current filesystem.
2. Resolve exactly one explicit scope and its mutation target.
3. Run a fresh read-only Git check against that repository.
4. Continue only when the repository is valid, the baseline revision is identifiable, and the worktree is clean.
5. Discover eligible subject-local JSON runs from the resolved scope.

Make zero writes until the scope, Git gate, and sample set all pass. Do not create or update a separate Git-state file.

If blocked, refuse workflow evolution only. Explain that baseline freezing, comparison, and rollback cannot be guaranteed. Recommend repairing the repository state, but never change Git without authorization. Recheck on every later request.

## Eligible History

Accept only runs using a current skill-owned JSON contract. Require matching skill identity, source paths and hashes, raw/refined output paths, a completed run, a present raw note with `status: raw`, and a present human-refined note with `status: refined`.

Legacy Markdown runs are not eligible yet. A later converter task will define their conversion. When only legacy runs or insufficient real JSON pairs exist, report the missing eligible history and make zero writes.

## Freeze And Select

Before producing experiment outputs, freeze by path and hash:

- active generation skill and applicable `.note-style.md` files;
- run manifests, sources, indexes, raw/refined notes, templates, prompts, active tools, and environment declarations;
- a 100-point rubric and hard acceptance gates.

Treat human-refined notes as the 100-point target for organization, style, and user preference, while verifying facts against original sources. Use the frozen pre-evolution output as baseline.

For `series/type` scope, select three non-contiguous completed pairs near the middle of the history. Exclude openings, closings, summaries, corrupt sources, and atypical one-offs unless targeted. Change only that series `.note-style.md`.

For `repository` scope, select one representative middle pair per eligible note type. Keep every `.note-style.md` byte-identical and change only the shared generation skill. Reject cross-type regressions.

Record selection and exclusion reasons. Do not repeatedly tune against the same samples without new held-out history.

## Isolated A/B Execution

When isolated agents are authorized:

1. Start baseline and candidate generators without inherited conversation.
2. Give each only its frozen task capsule and workflow identity; hide refined targets, rubrics, variant mappings, and conclusions.
3. Blind output identities.
4. Start independent reviewers without inherited conversation. Give them sources, mappings, rubric, both outputs, and refined targets, but not the intended winner.
5. Freeze reports before revealing identities. Bound inputs, report size, and stop conditions.

If isolation is unavailable or unauthorized, use a clean task context, record lower confidence, and do not claim blind independent review.

## Score And Decide

Score baseline and candidate against the same frozen rubric, covering evidence coverage and mappings, factual correctness, structure, usefulness and style, formatting, human refinement cost, side effects, and rule compliance.

Promote only when every applicable gate passes:

- no sample loses coverage, mapping integrity, or correctness;
- no sample needs more structural rewrite or human refinement;
- aggregate score improves without trading away safety or rule compliance;
- repository scope degrades no represented type;
- series/type scope changes only the target `.note-style.md`;
- hashes, identities, and blind mappings reconcile.

On any hard-gate failure, retain the frozen active version and keep the candidate inactive. Test attractive fragments only as a new candidate.

## Persist And Finish

Create an evolution run only after every precondition passes. Read [the evolution persistence contract](references/persistence-contract.md) completely before writing and follow it through completion. Do not update counters, schedules, or due-state after the decision.

## Completion Gates

- The Git gate is fresh and passing.
- Baseline, samples, rubric, and acceptance gates were frozen before candidate outputs.
- Generator target isolation and reviewer blindness are truthful.
- Mutation stayed within the selected scope.
- Failed candidates remain inactive and retained evidence reproduces the decision.