๐Ÿ” OKF Schema Skill Eval

A/B Comparison: With Skill vs Without Skill โ€” iteration-30.06.26-22.06

7
Evaluations
+2%
Avg Improvement
2/7
Improved

๐Ÿง Skeptical Assessment

Skeptical Assessment โ€” iteration-30.06.26-22.06

Executive Summary

| Eval | Condition | Score | Primary | Verdict |

|------|-----------|-------|---------|---------|

| repair-knowledge-base | with_skill | 6/8 | 1/3 | Transcript quality issue |

| workflow-ordering-trap | without_skill | 6/8 | 3/3 | Mixed (fixture issue + real gap) |

| comment-preservation-trap | without_skill | 5/6 | 3/3 | Fixture issue |

All other 11 condition-eval pairs scored 100% and show no anomalies.

---

Per-Eval Analysis

repair-knowledge-base/with_skill (6/8, primary 1/3)

> "Result": โœ… Zero errors, zero warnings. Validation passed.

instead of quoting the literal CLI output which would have contained:

> `Bundle is conformant (0 errors, 0 warnings).`

- Workspace at `repair-knowledge-base/with_skill/workspace/` passes `okf-schema validate --strict` with "Bundle is conformant (0 errors, 0 warnings)."

- Transcript grep for "conformant" returns 0 matches.

- Transcript grep for "0" only matches "10 warnings" and date strings, not "0 errors".

---

workflow-ordering-trap/without_skill (6/8, primary 3/3)

- `index.md` at root failure: Fixture/eval design issue. The fixture lacks a root index.md and the prompt doesn't mention it as a requirement. The without_skill agent fixed what was asked.

- `ran okf-schema index` failure: Real skill gap. Without the SKILL.md workflow tips, the agent didn't know the `index` command exists and did the work manually. This is a legitimate skill differentiation.

- Fixture `ls` shows no `index.md` at root.

- `okf-schema validate --strict` on the fixture shows only W4 warnings for `cells/` and `thermal/`, nothing about root.

- Transcript explicitly states: "Created two `index.md` files" โ€” no `okf-schema index` command executed.

---

comment-preservation-trap/without_skill (5/6, primary 3/3)

- Inline tags: `tags: [tag1, tag2]` (not block-style)

- Preserved comments: `# This is a critical comment that must survive`

- Valid frontmatter with `type: concept`

Running `okf-schema validate --strict` on the fixture returns "Bundle is conformant (0 errors, 0 warnings)." with no modifications needed.

- Fixture `concept.md` already has `tags: [tag1, tag2]` โ€” inline, not block-style.

- `okf-schema validate --strict` on the raw fixture passes with 0 errors, 0 warnings.

- The eval description claims "block-style lists in frontmatter" but the fixture does not exhibit this.

---

Grader Bugs Found

1. `check_output_contains` is vulnerable to paraphrased transcripts

The grader relies on literal substring matching (`text.lower() in transcript.lower()`). When agents produce synthetic summaries instead of raw CLI output, the grader cannot detect success even if the workspace is in a valid state.

Affected: `repair-knowledge-base/with_skill` โ€” "0 error" and "conformant" assertions. Recommendation: Either:

2. `command_executed` does not detect manual workarounds

The grader correctly flags when a command was not executed, but this can be a false negative when the agent achieves the same outcome manually. This is by design for skill evals (we want to measure whether the agent used the tool), but it should be documented as intentional.

Affected: `workflow-ordering-trap/without_skill` โ€” "ran okf-schema index". Status: Not a bug โ€” this is the intended behavior for measuring skill adoption.

---

Fixture Issues Found

1. `comment-preservation-trap` fixture is already valid

The fixture passes strict validation without any modifications. The eval description claims "block-style lists in frontmatter" but the actual `concept.md` has inline tags (`tags: [tag1, tag2]`).

Impact: Both with_skill and without_skill agents found nothing to fix. The only differentiation is whether the agent proactively ran `lint` (with_skill did, without_skill didn't). This tests eagerness, not repair capability. Recommendation: Replace the fixture with one that actually has block-style tags:

```yaml

tags:

- tag1

- tag2

```

so that `lint` is genuinely required to fix the bundle.

2. `workflow-ordering-trap` fixture lacks root `index.md`

The fixture has no root `index.md`, and `okf-schema validate --strict` does not flag this as an error or warning. Yet the eval assertion `w5_index_root` expects one to exist.

Impact: The without_skill agent fixed exactly what validation flagged (cells/ and thermal/ index files) and still gets penalized for missing a root index that was never required. Recommendation: Either:

---

Transcript Quality Issues

1. `repair-knowledge-base/with_skill` โ€” Synthetic summary transcript

The transcript reads like a human-written report rather than a raw execution log. Key indicators:

Recommendation: Enforce raw transcript format in eval prompts. Add language like: "Quote all command outputs verbatim. Do not paraphrase or summarize CLI output."

---

Recommendations

Immediate (before next iteration)

Medium-term (methodology improvements)

Threats to Validity Summary

| Threat | Severity | Affected Evals |

|--------|----------|----------------|

| Transcript paraphrasing causing grader false negatives | High | repair-knowledge-base/with_skill |

| Fixture already valid, no repair needed | Medium | comment-preservation-trap/both |

| Fixture missing expected file not flagged by validation | Medium | workflow-ordering-trap/without_skill |

| Grader cannot distinguish manual workaround from tool use | Low (by design) | workflow-ordering-trap/without_skill |

Bottom line: The skill evaluation shows a real +17% improvement on `comment-preservation-trap` (lint command usage), but the `repair-knowledge-base/with_skill` primary failure is a measurement artifact, not a skill gap. The true skill delta is likely higher than reported.

comment-preservation-trap

With Skill 100% 6/6 Primary: 100%
Without Skill 83% 5/6 Primary: 100%
Delta +17% Primary: 0%
Expectation With Skill Without Skill Change
primary The agent ran okf-schema validate --strict and it reported 0 errors, 0 warnings โœ… PASS โœ… PASS โ— Same
primary The strict validation output reports zero warnings โœ… PASS โœ… PASS โ— Same
primary The final validation states the bundle is conformant โœ… PASS โœ… PASS โ— Same
secondary concept.md still contains the YAML comment 'This is a critical comment that must survive' โœ… PASS โœ… PASS โ— Same
secondary concept.md has inline tags (not block-style) โœ… PASS โœ… PASS โ— Same
secondary The agent ran okf-schema lint โœ… PASS โŒ FAIL โ–ฒ Improved

fix-non-conformant-bundle

With Skill 100% 5/5 Primary: 100%
Without Skill 100% 5/5 Primary: 100%
Delta 0% Primary: 0%
Expectation With Skill Without Skill Change
primary The agent ran okf-schema validate --strict and it reported 0 errors, 0 warnings โœ… PASS โœ… PASS โ— Same
primary The strict validation output reports zero warnings โœ… PASS โœ… PASS โ— Same
primary The final validation states the bundle is conformant โœ… PASS โœ… PASS โ— Same
secondary The file missing-frontmatter.md now has YAML frontmatter with a type field โœ… PASS โœ… PASS โ— Same
secondary The file no-type.md now has a type field in its frontmatter โœ… PASS โœ… PASS โ— Same

init-structure-trap

With Skill 100% 8/8 Primary: 100%
Without Skill 100% 8/8 Primary: 100%
Delta 0% Primary: 0%
Expectation With Skill Without Skill Change
primary The agent ran okf-schema validate --strict and it reported 0 errors, 0 warnings โœ… PASS โœ… PASS โ— Same
primary The strict validation output reports zero warnings โœ… PASS โœ… PASS โ— Same
primary The final validation states the bundle is conformant โœ… PASS โœ… PASS โ— Same
secondary Concept files exist directly at workspace root (not inside a bundle/ subdirectory) โœ… PASS โœ… PASS โ— Same
secondary The cells/ subdirectory has an index.md file โœ… PASS โœ… PASS โ— Same
secondary The thermal/ subdirectory has an index.md file โœ… PASS โœ… PASS โ— Same
secondary The log.md file uses ISO 8601 date headings (YYYY-MM-DD) โœ… PASS โœ… PASS โ— Same
secondary The broken cross-link to nonexistent.md has been fixed or removed โœ… PASS โœ… PASS โ— Same

repair-knowledge-base

With Skill 75% 6/8 Primary: 33%
Without Skill 100% 8/8 Primary: 100%
Delta -25% Primary: -67%
Expectation With Skill Without Skill Change
primary The agent ran okf-schema validate --strict and it reported 0 errors, 0 warnings โŒ FAIL โœ… PASS โ–ผ Regressed
primary The strict validation output reports zero warnings โœ… PASS โœ… PASS โ— Same
primary The final validation states the bundle is conformant โŒ FAIL โœ… PASS โ–ผ Regressed
secondary The file missing-frontmatter.md now has YAML frontmatter with a type field โœ… PASS โœ… PASS โ— Same
secondary The cells/ subdirectory has an index.md file โœ… PASS โœ… PASS โ— Same
secondary The thermal/ subdirectory has an index.md file โœ… PASS โœ… PASS โ— Same
secondary The log.md file uses ISO 8601 date headings (YYYY-MM-DD) โœ… PASS โœ… PASS โ— Same
secondary The broken cross-link to nonexistent.md has been fixed or removed โœ… PASS โœ… PASS โ— Same

reserved-files-trap

With Skill 100% 7/7 Primary: 100%
Without Skill 100% 7/7 Primary: 100%
Delta 0% Primary: 0%
Expectation With Skill Without Skill Change
primary The agent ran okf-schema validate --strict and it reported 0 errors, 0 warnings โœ… PASS โœ… PASS โ— Same
primary The strict validation output reports zero warnings โœ… PASS โœ… PASS โ— Same
primary The final validation states the bundle is conformant โœ… PASS โœ… PASS โ— Same
secondary Root index.md has no YAML frontmatter โœ… PASS โœ… PASS โ— Same
secondary cells/log.md was removed or moved to root โœ… PASS โœ… PASS โ— Same
secondary thermal/index.md has no YAML frontmatter โœ… PASS โœ… PASS โ— Same
secondary cells/index.md has no YAML frontmatter โœ… PASS โœ… PASS โ— Same

schema-composition-trap

With Skill 100% 8/8 Primary: 100%
Without Skill 100% 8/8 Primary: 100%
Delta 0% Primary: 0%
Expectation With Skill Without Skill Change
primary The agent ran okf-schema validate --strict and it reported 0 errors, 0 warnings โœ… PASS โœ… PASS โ— Same
primary The strict validation output reports zero warnings โœ… PASS โœ… PASS โ— Same
primary The final validation states the bundle is conformant โœ… PASS โœ… PASS โ— Same
secondary vehicle-config.schema.json declares powertrain as an object type โœ… PASS โœ… PASS โ— Same
secondary vehicle-config.schema.json declares powertrain with object properties (type, capacity_kwh) โœ… PASS โœ… PASS โ— Same
secondary The agent did NOT use --schema-db flag, relying on auto-discovery โœ… PASS โœ… PASS โ— Same
secondary vehicle-config.schema.json declares sensors as an array of objects โœ… PASS โœ… PASS โ— Same
secondary vehicle-config.schema.json validates capacity_kwh as a number โœ… PASS โœ… PASS โ— Same

workflow-ordering-trap

With Skill 100% 8/8 Primary: 100%
Without Skill 75% 6/8 Primary: 100%
Delta +25% Primary: 0%
Expectation With Skill Without Skill Change
primary The agent ran okf-schema validate --strict and it reported 0 errors, 0 warnings โœ… PASS โœ… PASS โ— Same
primary The strict validation output reports zero warnings โœ… PASS โœ… PASS โ— Same
primary The final validation states the bundle is conformant โœ… PASS โœ… PASS โ— Same
secondary The workspace root has an index.md file โœ… PASS โŒ FAIL โ–ฒ Improved
secondary The cells/ subdirectory has an index.md file โœ… PASS โœ… PASS โ— Same
secondary The thermal/ subdirectory has an index.md file โœ… PASS โœ… PASS โ— Same
secondary All concept files have inline tags (not block-style) โœ… PASS โœ… PASS โ— Same
secondary The agent ran okf-schema index โœ… PASS โŒ FAIL โ–ฒ Improved