Compare commits

...
Author SHA1 Message Date
jarvis-at-skic e22d3a5c13 docs: separate workflow effectiveness from skill health
Build and publish Eldorado documentation / build (pull_request) Successful in 52s
2026-10-08 11:05:00 +00:00
jarvis-at-skic 386133c8b6 Merge pull request 'docs: separate Measurement registry and workflow Baseline' (#35) from feat/measurement-baseline-separation into main
Build and publish Eldorado documentation / build (push) Successful in 44s
2026-10-07 06:47:31 -07:00
12 changed files with 142 additions and 587 deletions

No files matched your search

@@ -1,284 +1,20 @@
{
"schema_version": 1,
"diagram_type": "architecture",
"meta": {
"title": "Candidate metric registry",
"output": "static/diagrams/strategy-measurement-mobile/index.html",
"quality_profile": "showcase",
"legend": {
"mode": "hidden"
},
"viewBox": [
880,
2450
]
},
"meta": {"title": "Two connected measurement tracks", "output": "static/diagrams/strategy-measurement-mobile/index.html", "quality_profile": "showcase", "legend": {"mode": "hidden"}, "viewBox": [880, 2450]},
"components": [
{
"id": "registry",
"type": "backend",
"label": "Available choices",
"tag": "Registry, not a rollout plan",
"sublabel": "16 candidate contracts\nUse only what is relevant\nNo mandatory collection",
"pos": [
90,
50
],
"size": [
700,
350
],
"icon": "none"
},
{
"id": "qualification",
"type": "frontend",
"label": "Selection + reach",
"tag": "Qualification / supported use",
"sublabel": "Precision, recall, coverage\nApproved-workflow adoption",
"pos": [
90,
450
],
"size": [
700,
350
],
"icon": "none"
},
{
"id": "outcomes",
"type": "frontend",
"label": "Outcomes + delivery",
"tag": "Task / change / service",
"sublabel": "Success, quality, DORA\nBusiness acceptance",
"pos": [
90,
850
],
"size": [
700,
350
],
"icon": "none"
},
{
"id": "experience",
"type": "frontend",
"label": "Safety + cost + experience",
"tag": "Policy / spend / people",
"sublabel": "Policy effects, outcome cost\nConfidence + cognitive load",
"pos": [
90,
1250
],
"size": [
700,
350
],
"icon": "none"
},
{
"id": "health",
"type": "frontend",
"label": "Skill health",
"tag": "Catalog revisions",
"sublabel": "Substantive-review coverage\nOwnership + review evidence",
"pos": [
90,
1650
],
"size": [
700,
350
],
"icon": "none"
},
{
"id": "contract",
"type": "external",
"label": "Inspect a candidate",
"tag": "Every entry explains",
"sublabel": "Meaning + applicability\nCalculation + required inputs\nLimits + implementation status\n9 prototype / 7 unimplemented",
"pos": [
90,
2050
],
"size": [
700,
350
],
"icon": "none"
}
{"id": "workflow", "type": "backend", "label": "Workflow effectiveness", "tag": "01 / Baseline current work", "sublabel": "Accepted work, time, failures\nCost, effort + experience\nSelect relevant contracts only\nSkills need not exist yet", "pos": [90, 50], "size": [700, 350], "icon": "none"},
{"id": "compare", "type": "backend", "label": "Compare the same outcomes", "tag": "02 / After introducing skills", "sublabel": "Same workflow + acceptance\nSame follow-up + source coverage\nKeep gaps and task mix visible\nBefore / after is not causality", "pos": [90, 450], "size": [700, 350], "icon": "none"},
{"id": "interpret", "type": "external", "label": "Is work getting better?", "tag": "03 / Interpret workflow evidence", "sublabel": "Balance value, quality and risk\nMore adoption is not better work\nKeep live outcomes separate\nfrom skill evaluation cases", "pos": [90, 850], "size": [700, 350], "icon": "none"},
{"id": "skills", "type": "frontend", "label": "Skills effectiveness & health", "tag": "01 / Qualify named skill versions", "sublabel": "Selection precision + recall\nSeparate evaluation evidence\nNo applicable skills: N/A\nNot a zero workflow baseline", "pos": [90, 1250], "size": [700, 350], "icon": "none"},
{"id": "observe", "type": "frontend", "label": "Observe use + upkeep", "tag": "02 / Adoption and maintenance", "sublabel": "Supported bundle coverage\nApproved-workflow adoption\nSubstantive review evidence\nMissing observations: unknown", "pos": [90, 1650], "size": [700, 350], "icon": "none"},
{"id": "improve", "type": "external", "label": "Improve, retain or retire", "tag": "03 / Use both tracks together", "sublabel": "16 optional candidate contracts\n9 prototype / 7 unimplemented\nNo mandatory collection\nNo installed telemetry claimed", "pos": [90, 2050], "size": [700, 350], "icon": "none"}
],
"connections": [
{
"id": "registry-qualification",
"from": "registry",
"to": "qualification",
"label": "",
"fromSide": "left",
"toSide": "left",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
45,
225
],
[
45,
625
]
]
},
{
"id": "qualification-contract",
"from": "qualification",
"to": "contract",
"label": "",
"fromSide": "right",
"toSide": "right",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
835,
625
],
[
835,
2225
]
]
},
{
"id": "registry-outcomes",
"from": "registry",
"to": "outcomes",
"label": "",
"fromSide": "left",
"toSide": "left",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
45,
225
],
[
45,
1025
]
]
},
{
"id": "outcomes-contract",
"from": "outcomes",
"to": "contract",
"label": "",
"fromSide": "right",
"toSide": "right",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
835,
1025
],
[
835,
2225
]
]
},
{
"id": "registry-experience",
"from": "registry",
"to": "experience",
"label": "",
"fromSide": "left",
"toSide": "left",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
45,
225
],
[
45,
1425
]
]
},
{
"id": "experience-contract",
"from": "experience",
"to": "contract",
"label": "",
"fromSide": "right",
"toSide": "right",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
835,
1425
],
[
835,
2225
]
]
},
{
"id": "registry-health",
"from": "registry",
"to": "health",
"label": "",
"fromSide": "left",
"toSide": "left",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
45,
225
],
[
45,
1825
]
]
},
{
"id": "health-contract",
"from": "health",
"to": "contract",
"label": "",
"fromSide": "right",
"toSide": "right",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
835,
1825
],
[
835,
2225
]
]
}
{"id": "workflow-compare", "from": "workflow", "to": "compare", "label": "", "fromSide": "bottom", "toSide": "top", "route": "straight", "width": 4, "variant": "default"},
{"id": "compare-interpret", "from": "compare", "to": "interpret", "label": "", "fromSide": "bottom", "toSide": "top", "route": "straight", "width": 4, "variant": "default"},
{"id": "skills-observe", "from": "skills", "to": "observe", "label": "", "fromSide": "bottom", "toSide": "top", "route": "straight", "width": 4, "variant": "default"},
{"id": "observe-improve", "from": "observe", "to": "improve", "label": "", "fromSide": "bottom", "toSide": "top", "route": "straight", "width": 4, "variant": "default"},
{"id": "interpret-improve", "from": "interpret", "to": "improve", "label": "", "fromSide": "right", "toSide": "right", "route": "straight", "width": 4, "variant": "default", "via": [[835, 1025], [835, 2225]]}
]
}
}
+13 -277
View File
@@ -1,284 +1,20 @@
{
"schema_version": 1,
"diagram_type": "architecture",
"meta": {
"title": "Candidate metric registry",
"output": "static/diagrams/strategy-measurement/index.html",
"quality_profile": "showcase",
"legend": {
"mode": "hidden"
},
"viewBox": [
2400,
1120
]
},
"meta": {"title": "Two connected measurement tracks", "output": "static/diagrams/strategy-measurement/index.html", "quality_profile": "showcase", "legend": {"mode": "hidden"}, "viewBox": [2400, 960]},
"components": [
{
"id": "registry",
"type": "backend",
"label": "Available choices",
"tag": "Registry, not a rollout plan",
"sublabel": "16 candidate contracts\nUse only what is relevant\nNo mandatory collection",
"pos": [
40,
405
],
"size": [
600,
310
],
"icon": "none"
},
{
"id": "qualification",
"type": "frontend",
"label": "Selection + reach",
"tag": "Qualification / supported use",
"sublabel": "Precision, recall, coverage\nApproved-workflow adoption",
"pos": [
810,
40
],
"size": [
700,
220
],
"icon": "none"
},
{
"id": "outcomes",
"type": "frontend",
"label": "Outcomes + delivery",
"tag": "Task / change / service",
"sublabel": "Success, quality, DORA\nBusiness acceptance",
"pos": [
810,
310
],
"size": [
700,
220
],
"icon": "none"
},
{
"id": "experience",
"type": "frontend",
"label": "Safety + cost + experience",
"tag": "Policy / spend / people",
"sublabel": "Policy effects, outcome cost\nConfidence + cognitive load",
"pos": [
810,
580
],
"size": [
700,
220
],
"icon": "none"
},
{
"id": "health",
"type": "frontend",
"label": "Skill health",
"tag": "Catalog revisions",
"sublabel": "Substantive-review coverage\nOwnership + review evidence",
"pos": [
810,
850
],
"size": [
700,
220
],
"icon": "none"
},
{
"id": "contract",
"type": "external",
"label": "Inspect a candidate",
"tag": "Every entry explains",
"sublabel": "Meaning + applicability\nCalculation + required inputs\nLimits + implementation status\n9 prototype / 7 unimplemented",
"pos": [
1710,
355
],
"size": [
650,
360
],
"icon": "none"
}
{"id": "workflow", "type": "backend", "label": "Workflow effectiveness", "tag": "01 / Baseline current work", "sublabel": "Accepted work, time, failures\nCost, effort + experience\nSelect relevant contracts only\nSkills need not exist yet", "pos": [40, 40], "size": [720, 310], "icon": "none"},
{"id": "compare", "type": "backend", "label": "Compare the same outcomes", "tag": "02 / After introducing skills", "sublabel": "Same workflow + acceptance\nSame follow-up + source coverage\nKeep gaps and task mix visible\nBefore / after is not causality", "pos": [840, 40], "size": [720, 310], "icon": "none"},
{"id": "interpret", "type": "external", "label": "Is work getting better?", "tag": "03 / Interpret workflow evidence", "sublabel": "Balance value, quality and risk\nMore adoption is not better work\nKeep live outcomes separate\nfrom skill evaluation cases", "pos": [1640, 40], "size": [720, 310], "icon": "none"},
{"id": "skills", "type": "frontend", "label": "Skills effectiveness & health", "tag": "01 / Qualify named skill versions", "sublabel": "Selection precision + recall\nSeparate evaluation evidence\nNo applicable skills: N/A\nNot a zero workflow baseline", "pos": [40, 590], "size": [720, 310], "icon": "none"},
{"id": "observe", "type": "frontend", "label": "Observe use + upkeep", "tag": "02 / Adoption and maintenance", "sublabel": "Supported bundle coverage\nApproved-workflow adoption\nSubstantive review evidence\nMissing observations: unknown", "pos": [840, 590], "size": [720, 310], "icon": "none"},
{"id": "improve", "type": "external", "label": "Improve, retain or retire", "tag": "03 / Use both tracks together", "sublabel": "16 optional candidate contracts\n9 prototype / 7 unimplemented\nNo mandatory collection\nNo installed telemetry claimed", "pos": [1640, 590], "size": [720, 310], "icon": "none"}
],
"connections": [
{
"id": "registry-qualification",
"from": "registry",
"to": "qualification",
"label": "",
"fromSide": "right",
"toSide": "left",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
715,
560
],
[
715,
150
]
]
},
{
"id": "qualification-contract",
"from": "qualification",
"to": "contract",
"label": "",
"fromSide": "right",
"toSide": "left",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
1605,
150
],
[
1605,
535
]
]
},
{
"id": "registry-outcomes",
"from": "registry",
"to": "outcomes",
"label": "",
"fromSide": "right",
"toSide": "left",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
715,
560
],
[
715,
420
]
]
},
{
"id": "outcomes-contract",
"from": "outcomes",
"to": "contract",
"label": "",
"fromSide": "right",
"toSide": "left",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
1605,
420
],
[
1605,
535
]
]
},
{
"id": "registry-experience",
"from": "registry",
"to": "experience",
"label": "",
"fromSide": "right",
"toSide": "left",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
715,
560
],
[
715,
690
]
]
},
{
"id": "experience-contract",
"from": "experience",
"to": "contract",
"label": "",
"fromSide": "right",
"toSide": "left",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
1605,
690
],
[
1605,
535
]
]
},
{
"id": "registry-health",
"from": "registry",
"to": "health",
"label": "",
"fromSide": "right",
"toSide": "left",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
715,
560
],
[
715,
960
]
]
},
{
"id": "health-contract",
"from": "health",
"to": "contract",
"label": "",
"fromSide": "right",
"toSide": "left",
"route": "straight",
"width": 4,
"variant": "default",
"via": [
[
1605,
960
],
[
1605,
535
]
]
}
{"id": "workflow-compare", "from": "workflow", "to": "compare", "label": "", "fromSide": "right", "toSide": "left", "route": "straight", "width": 4, "variant": "default"},
{"id": "compare-interpret", "from": "compare", "to": "interpret", "label": "", "fromSide": "right", "toSide": "left", "route": "straight", "width": 4, "variant": "default"},
{"id": "skills-observe", "from": "skills", "to": "observe", "label": "", "fromSide": "right", "toSide": "left", "route": "straight", "width": 4, "variant": "default"},
{"id": "observe-improve", "from": "observe", "to": "improve", "label": "", "fromSide": "right", "toSide": "left", "route": "straight", "width": 4, "variant": "default"},
{"id": "interpret-improve", "from": "interpret", "to": "improve", "label": "", "fromSide": "bottom", "toSide": "top", "route": "straight", "width": 4, "variant": "default"}
]
}
}
+3 -1
View File
@@ -24,7 +24,9 @@ Describe the task, team or service, intended outcome, current tools, handoffs, c
## Select relevant metrics, with reasons
Choose the registry entries that answer this workflow's questions. Record why each selected metric applies, what decision it can inform, and why other candidates are irrelevant or deferred. There is no required universal subset. A service-level DORA metric, a qualification test and a people survey have different populations; they are not interchangeable.
Start with **Workflow effectiveness**: select relevant current-workflow outcomes before standardized skills adoption—accepted work, delivery time, failures/rework, cost, human effort/experience or business acceptance where the contracts apply. Choose the registry entries that answer this workflow's questions. Record why each selected metric applies, what decision it can inform, and why other candidates are irrelevant or deferred. There is no required universal subset. A service-level DORA metric, a qualification test and a people survey have different populations; they are not interchangeable.
Keep **Skills effectiveness & health** separate. If no applicable skills exist, selection, bundle, adoption and review measures may be N/A, not zero; they are not prerequisites for baselining current work. If skills already exist, record that starting context and qualify named revisions separately. Do not mix sandbox skill evaluations into validated workflow task success or live policy-effect rates.
Agree what counts as a started task, independent acceptance and completed follow-up before counting outcomes. Freeze eligibility and acceptance rules and verify event joins. Select a complete comparable workflow cycle and a predeclared precision/sample requirement appropriate to the decision. Do not select a convenient end date after seeing results. Where those requirements cannot be met, record the resulting evidence limitation.
+35 -20
View File
@@ -3,7 +3,7 @@ id: index
slug: /measurement
title: Skills Measurement
sidebar_label: Measurement
description: Registry of available candidate KPIs and metrics, their applicability, evidence requirements, calculations and limitations.
description: Optional contracts for workflow effectiveness and skills effectiveness and health, with distinct populations and honest implementation limits.
pagination_prev: stage-01-skills-adoption
pagination_next: baseline
hide_table_of_contents: true
@@ -13,15 +13,15 @@ import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
<div className="strategy-content">
Browse available candidate KPIs and metrics. Registry inclusion does not require a metric to be used, collected or baselined. Count use separately from outcomes—more use does not by itself mean better work.
Start with how work performs today; compare relevant outcomes after introducing skills. Separately assess whether the skills are effective, supported, used and maintained. Registry inclusion does not require a metric to be used, collected or baselined. More adoption does not prove improved work.
<ArchifyDiagram name="strategy-measurement" title="An optional metric registry: browse distinct questions and inspect each contract" story />
<ArchifyDiagram name="strategy-measurement" title="Workflow effectiveness / Skills effectiveness & health" story />
**Target operating model — candidate definitions, not installed telemetry or a collection plan.** Proposed owners and cadences in the contracts apply only if selected and agreed for a workflow.
## Read a candidate contract
Each entry explains meaning and applicability, calculation, required inputs and evidence, exclusions, missing-evidence behavior, limitations and implementation status. Selection measures concern qualification; coverage and adoption concern reach; DORA measures concern service delivery. Outcome, safety, cost, experience and maintenance measures retain their distinct populations. A delivery metric need not fit a non-delivery workflow.
Each entry explains meaning and applicability, calculation, required inputs and evidence, exclusions, missing-evidence behavior, limitations and implementation status. The two groups below classify every contract by its primary question; conditional reuse never merges populations. A delivery metric need not fit a non-delivery workflow.
To select a relevant subset and establish actual starting evidence, use [Baseline](../baseline.mdx). Pilot application belongs to [Adoption](../skills-adoption.mdx); ongoing interpretation belongs to [Maintenance](../skills-maintenance.mdx).
@@ -33,22 +33,37 @@ The nine calculations cover task success, selection precision and recall, change
Each contract is a prospective definition, not a rollout obligation. No live source or observed baseline is established. N and D refer to the numerator and denominator shown for that metric.
1. [Validated task success](./validated-task-success.mdx) — prototype calculation
2. [Skill selection precision](./skill-selection-precision.mdx) — prototype calculation
3. [Skill selection recall](./skill-selection-recall.mdx) — prototype calculation
4. [Supported bundle coverage](./supported-bundle-coverage.mdx) — unimplemented metric
5. [Approved-workflow adoption](./approved-workflow-adoption.mdx) — unimplemented metric
6. [Change lead time](./change-lead-time.mdx) — unimplemented metric
7. [Deployment frequency](./deployment-frequency.mdx) — unimplemented metric
8. [Change fail rate](./change-fail-rate.mdx) — prototype calculation
9. [Failed deployment recovery time](./failed-deployment-recovery-time.mdx) — unimplemented metric
10. [Deployment rework rate](./deployment-rework-rate.mdx) — prototype calculation
11. [Changes with escaped quality issues](./changes-with-escaped-quality-issues.mdx) — prototype calculation
12. [Confirmed policy effects](./confirmed-policy-effects.mdx) — prototype calculation
13. [Cost per accepted outcome](./cost-per-accepted-outcome.mdx) — prototype calculation
14. [Verification confidence and cognitive load](./verification-confidence-and-cognitive-load.mdx) — prototype calculation
15. [Skills within substantive review window](./skills-within-substantive-review-window.mdx) — unimplemented metric
16. [Workflow-specific business acceptance](./workflow-specific-business-acceptance.mdx) — unimplemented metric
### Workflow effectiveness
**Is the work getting better?** Baseline relevant current-workflow outcomes even before standardized skills exist, then compare the same outcomes during adoption and maintenance. Use comparable task mix, acceptance rules, follow-up periods and source coverage. Before/after trends alone are not causal evidence of a skills benefit.
1. [Validated task success](./validated-task-success.mdx) — **Prototype calculation.** Independently accepted outcomes among matured workflow starts; failures, abandonment and unresolved outcomes remain in the denominator.
2. [Change lead time](./change-lead-time.mdx) — **Unimplemented metric.** Delivery time for production changes in one service, not general task duration.
3. [Deployment frequency](./deployment-frequency.mdx) — **Unimplemented metric.** Production delivery frequency for one service; frequency alone is not value.
4. [Change fail rate](./change-fail-rate.mdx) — **Prototype calculation.** Production deployments causing failures; requires joined change/incident evidence.
5. [Failed deployment recovery time](./failed-deployment-recovery-time.mdx) — **Unimplemented metric.** Recovery from failed production deployments; conditional on eligible incidents.
6. [Deployment rework rate](./deployment-rework-rate.mdx) — **Prototype calculation.** Unplanned corrective production deployments, not all forms of task rework.
7. [Changes with escaped quality issues](./changes-with-escaped-quality-issues.mdx) — **Prototype calculation.** Accepted changes with confirmed downstream issues after follow-up.
8. [Confirmed policy effects](./confirmed-policy-effects.mdx) — **Prototype calculation.** Safety of supported workflow attempts; governed skill trials are a separate evaluation population, never pooled with live work.
9. [Cost per accepted outcome](./cost-per-accepted-outcome.mdx) — **Prototype calculation.** Cost of the matured workflow cohort, including unsuccessful attempts and recorded review/rework effort. Missing cost buckets remain partial.
10. [Verification confidence and cognitive load](./verification-confidence-and-cognitive-load.mdx) — **Prototype calculation.** Anonymous cohort experience: confidence, workload and usefulness separately, not measured time savings.
11. [Workflow-specific business acceptance](./workflow-specific-business-acceptance.mdx) — **Unimplemented metric.** Acceptance against an agreed departmental rubric; requires a defined workflow and independent evidence.
Human effort is recorded as review/rework inputs where the cost contract supports it; the experience survey describes perception. Neither elapsed delivery time nor token counts establish effort saved. If the current workflow lacks the event semantics required by a contract (for example, governed attempts), record it as not applicable or unavailable with a reason; do not relabel unrelated records to manufacture a baseline.
### Skills effectiveness & health
**Are the skills fit for use and kept fit?** Qualify named skills and versions, observe supported use during adoption, and review or retire them in maintenance. Without applicable skills, bundles or enrolled use, skill-specific measures may be **N/A, not zero**. Once a population exists, missing observations are unknown, not evidence of non-use or good health.
1. [Skill selection precision](./skill-selection-precision.mdx) — **Prototype calculation.** Did the evaluated selection choose an applicable skill? Requires labeled qualification cases.
2. [Skill selection recall](./skill-selection-recall.mdx) — **Prototype calculation.** Were expected skills selected? Requires the same labeled qualification population.
3. [Supported bundle coverage](./supported-bundle-coverage.mdx) — **Unimplemented metric.** Are expected active installations on supported, non-revoked bundles/adapters?
4. [Approved-workflow adoption](./approved-workflow-adoption.mdx) — **Unimplemented metric.** Is the enrolled cohort using approved skills in eligible workflows? Installation/loading is not use.
5. [Skills within substantive review window](./skills-within-substantive-review-window.mdx) — **Unimplemented metric.** Do active approved revisions have current owners and substantive review evidence?
**Task-success population matters.** The canonical validated-task-success contract above measures workflow outcomes, not an evaluation benchmark. A named skill/version can be examined as a predeclared live-workflow slice under that same contract, without counting retries or multiple skills as extra tasks or attributing causality. Sandbox/evaluation cases remain excluded: a named skill/version evaluation must be reported separately with its own declared cases, acceptance evidence and limits. It is not an additional implemented calculation or a second conflicting task-success formula. The canonical page explains this boundary. Likewise, keep policy-effect evaluation trials separate from live attempts.
Use both tracks together to decide whether to improve, retain or retire a skill. Higher selection scores, wider adoption or current reviews cannot substitute for accepted work, safety, cost and human experience.
Read [Collection and safeguards](./collection-and-safeguards.mdx) for shared interpretation, event and privacy rules. [Run the synthetic measurement example](./synthetic-example.mdx) for reproducible arithmetic and limits.
@@ -29,6 +29,14 @@ Confirmed independently accepted tasks as a share of all eligible initiated task
| Gaming and limits | Split easy tasks or omit starts; reconcile starts to approved backlog and audit acceptance rubrics. Descriptive signal, not causal AI productivity attribution. Source completeness, task mix and sampling limit inference; report uncertainty. Maturation horizon is workflow-specific and must be approved; no automatic abandonment on timeout. |
{/* contract:end */}
## Workflow outcomes versus skill/version evaluation
This contract belongs to **Workflow effectiveness**. Use the same matured-start population and independent acceptance rules before and after introducing skills; skills are not required for a workflow outcome to exist. Do not narrow the later denominator to successful skill invocations.
For **Skills effectiveness & health**, a predeclared slice of live workflow tasks using a named skill/version may reuse this contract unchanged. Keep the parent cohort visible, report exact versions and selection limits, and count each task once across retries, skills and clients. Overlapping skill slices must not be summed. This is descriptive evidence, not proof that the skill caused success.
A sandbox or qualification evaluation of a named skill/version is a different population and remains excluded by this contract. Declare its cases, skill/version, client/model configuration, acceptance rubric and observed results separately; never combine those cases with live workflow starts or present their results as this prototype's workflow rate. This page does not introduce an implemented skill-evaluation metric or an alternative formula. No applicable skill means that skill-specific evaluation is N/A, not a zero workflow success rate.
Read the shared [collection and safeguards](./collection-and-safeguards.mdx) before collecting data; see the [synthetic example and limits](./synthetic-example.mdx).
Return to [Skills Measurement](./index.mdx).
+3 -1
View File
@@ -13,7 +13,7 @@ import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
## When should a pilot become a team workflow?
Expand only when a bounded canary produces independently accepted work and useful feedback. Teach people to verify artifacts and recover without AI, not merely invoke a skill.
Expand only when a bounded canary produces independently accepted work and useful feedback. Teach people to verify artifacts and recover without AI, not merely invoke a skill. Compare **Workflow effectiveness** with the current-workflow baseline; observe **Skills effectiveness & health** separately as skills enter use. More adoption does not prove improved work, and before/after trends alone are not causal evidence.
<ArchifyDiagram name="strategy-adoption" title="Choose a workflow, coach a canary, verify outcomes and improve before expansion" story />
@@ -60,6 +60,8 @@ Recorded compute spend is **EUR 60 / 1 = EUR 60** per accepted outcome—a **par
### Revisit selection as adoption expands
Selection precision/recall qualify named skill versions against labeled cases; they do not measure real-workflow acceptance. Keep any skill/version evaluation separate from the live task-success cohort. Skill-specific measures with no applicable population are N/A, not zero; missing evidence for an existing population remains unknown.
Keep relevant outcome evidence comparable; add reach measures only if they answer the expanded workflow's questions. For [supported bundle coverage](./measurement/supported-bundle-coverage.mdx), freeze the expected active installation inventory and compare observed bundle/adapter revisions to support and revocation records. Offline or stale entries stay in the denominator. Platform & IT is the proposed weekly and at-revocation reviewer.
For [approved-workflow adoption](./measurement/approved-workflow-adoption.mdx), freeze the lawfully enrolled participant cohort and distinguish qualified-adapter observations from labeled declarations. Report the observed lower bound with source coverage: missing use is unknown; installation and loading are not use. Data & AI is the proposed monthly reviewer. No invocation quotas or employee rankings. Return to Baseline for a new workflow rather than treating rollout as company-wide metric collection.
+2 -2
View File
@@ -13,7 +13,7 @@ import ArchifyDiagram from '@site/src/components/ArchifyDiagram';
## What happens when a skill drifts or causes harm?
Monitor usefulness and safety throughout a revision's life. Unsafe behavior triggers containment; a correction returns through independent tests and approval, never automatic reinstatement.
Monitor both **Workflow effectiveness** (comparable outcomes, safety, cost and human experience) and **Skills effectiveness & health** (selection, supported use and substantive review) throughout a revision's life. Use the evidence to improve, retain or retire skills; adoption or current review dates alone do not prove better work. Unsafe behavior triggers containment; a correction returns through independent tests and approval, never automatic reinstatement.
<ArchifyDiagram name="strategy-maintenance" title="Monitor, triage and test corrections; promote safely or contain and roll back" story />
@@ -49,7 +49,7 @@ Owner ratification is required before adoption. Review earlier after incidents o
## Keep selected evidence useful
Continue the measures agreed for the workflow in [Baseline](./baseline.mdx) and applied during [Adoption](./skills-adoption.mdx). Revisit relevance when scope changes; the [registry](./measurement/index.mdx) is a source of choices, not a requirement to collect every metric.
Continue the measures agreed for the workflow in [Baseline](./baseline.mdx) and applied during [Adoption](./skills-adoption.mdx). Revisit relevance when scope changes; the [registry](./measurement/index.mdx) is a source of choices, not a requirement to collect every metric. Preserve current-workflow comparisons separately from named skill/version evaluations. No applicable skill population is N/A, not zero; missing evidence for existing revisions is unknown and must not improve reported health.
If substantive-review coverage is selected, join each active approved catalog revision to its owner, substantive review evidence and due date. Apply [review coverage](./measurement/skills-within-substantive-review-window.mdx): revisions with all three current / all active approved revisions × 100. The proposed Data & AI review is monthly and at each release, subject to agreement. Report overdue/ownerless revisions and deprecated or revoked versions still in use—not just a percentage.
+4 -4
View File
@@ -25,12 +25,12 @@ Skills topology connects what skills exist, how they relate, when they are used
## Put the foundation into practice
- [Measurement](./measurement/index.mdx) — browse available candidate metrics; inclusion does not require collection or baselining.
- [Baseline](./baseline.mdx) — understand a workflow, select relevant metrics and record feasible starting evidence or explicit gaps.
- [Measurement](./measurement/index.mdx) — distinguish Workflow effectiveness from Skills effectiveness & health; candidate inclusion does not require collection or baselining.
- [Baseline](./baseline.mdx) — understand current workflow outcomes first, select relevant metrics and record feasible starting evidence or explicit gaps; absent skills are not zero performance.
- [Governance](./skills-governance.mdx) — define ownership, authority and approval of skills.
- [Quality](./skills-quality.mdx) — qualify skills and verify their outcomes before wider use.
- [Adoption](./skills-adoption.mdx) — coach bounded workflows with a supported client and a manual path.
- [Maintenance](./skills-maintenance.mdx) — review feedback, control versions and recover from unsafe updates.
- [Adoption](./skills-adoption.mdx) — compare workflow outcomes and observe skill use separately, with a supported client and a manual path.
- [Maintenance](./skills-maintenance.mdx) — monitor both tracks to improve or retire skills, control versions and recover from unsafe updates.
Proven skills, measurements and working practices support [Stage - 02 - Autonomous Agent](./stage-02-autonomous-agent.mdx); adoption alone does not grant autonomous execution authority.
+29 -3
View File
@@ -19,6 +19,9 @@ const fs = require('node:fs');
assert((await page.title()).startsWith('Skills Measurement |'));
assert.equal(await page.locator('.strategy-content details').count(), 0);
assert.equal(await page.locator('.strategy-content h2').count(), 2);
assert.deepEqual((await page.locator('.strategy-content h3').allTextContents()).map(text => text.replaceAll('\u200b', '')), ['Workflow effectiveness', 'Skills effectiveness & health']);
assert.equal(await page.locator('.strategy-content ol').count(), 2);
assert.equal(await page.locator('.strategy-content ol > li').count(), 16);
if (width < 700) await page.getByRole('button', {name:'Toggle navigation bar'}).click();
const menu = page.locator('.theme-doc-sidebar-menu .menu__link').filter({visible:true});
await menu.first().waitFor({state:'visible'});
@@ -41,7 +44,7 @@ const fs = require('node:fs');
await page.waitForFunction(() => document.documentElement.dataset.theme === 'dark');
await frame.locator('#btn-theme').click();
await page.waitForFunction(() => document.documentElement.dataset.theme === 'light');
for (const preset of ['blueprint','classic']) {
for (const preset of ['signal-flow','blueprint','editorial','classic']) {
await frame.locator('#btn-preset').click();
await frame.locator(`[data-preset-value="${preset}"]`).click();
assert.equal(await frame.locator('html').getAttribute('data-preset'), preset);
@@ -51,7 +54,30 @@ const fs = require('node:fs');
assert.equal(await download.failure(), null);
const path = `${output}/${width}.svg`; await download.saveAs(path);
const svg = fs.readFileSync(path, 'utf8');
assert(svg.includes('Available choices') && svg.includes('No mandatory collection'));
assert(svg.includes('Workflow effectiveness') && svg.includes('Skills effectiveness &amp; health') && svg.includes('No mandatory collection'));
const exports = ['svg'];
for (const format of ['png','jpeg','webp','svg-light','svg-dark','webm']) {
await frame.locator('#btn-export').click();
const option = frame.locator(`[data-format="${format}"]`);
if (await option.isDisabled()) { exports.push(`${format}:unsupported`); await frame.locator('#btn-export').click(); continue; }
const [file] = await Promise.all([page.waitForEvent('download', {timeout:60000}), option.click()]);
assert.equal(await file.failure(), null);
const target = `${output}/${width}-${format}-${file.suggestedFilename()}`;
await file.saveAs(target);
const bytes = fs.readFileSync(target); assert(bytes.length > 1000);
if (format.startsWith('svg')) assert(bytes.toString().includes('eldorado-skills-typography'));
else {
const mime = {png:'image/png', jpeg:'image/jpeg', webp:'image/webp', webm:'video/webm'}[format];
const dimensions = await page.evaluate(async ({mime,data}) => {
const media = document.createElement(mime.startsWith('video') ? 'video' : 'img');
const ready = new Promise((resolve,reject) => {media[mime.startsWith('video') ? 'onloadedmetadata' : 'onload'] = resolve; media.onerror = reject;});
media.src = `data:${mime};base64,${data}`; await ready;
return [media.videoWidth || media.naturalWidth, media.videoHeight || media.naturalHeight];
}, {mime, data:bytes.toString('base64')});
assert(dimensions.every(n => n > 0));
}
exports.push(format);
}
const opener = panel.getByRole('button', {name:/^Expand /});
await opener.click();
const close = panel.getByRole('button', {name:'Close full-screen diagram', exact:true});
@@ -76,7 +102,7 @@ const fs = require('node:fs');
assert.equal(new Set(links.map(h => new URL(h).pathname)).size, 18);
assert(!await page.evaluate(() => document.documentElement.scrollWidth > innerWidth));
assert.deepEqual(errors, []);
results.push({width, geometry, links:links.length, title:true, sidebar:true, controls:true, export:true, reference:true});
results.push({width, geometry, links:links.length, title:true, sidebar:true, controls:true, exports, reference:true});
fs.writeFileSync(`${output}/results.json`, JSON.stringify(results,null,2));
await context.close();
}
+2
View File
@@ -40,6 +40,8 @@ const assert=require('node:assert/strict');
await panel.scrollIntoViewIfNeeded();await page.screenshot({path:`${out}/${topic}-${width}-${theme}-inline.png`});
const open=panel.getByRole('button',{name:/^Expand /});await open.click();const close=panel.getByRole('button',{name:'Close full-screen diagram',exact:true});await close.waitFor({state:'visible'});
const expanded=await(await panel.locator('dialog iframe').elementHandle()).contentFrame();await expanded.locator('svg[role="img"]').waitFor();
await expanded.waitForFunction(t=>document.documentElement.dataset.theme===t,theme);
await panel.locator('dialog').evaluate(n=>n.scrollTop=0);
assert((await expanded.url()).includes(width<=1100?`${topic}-mobile/`:`${topic}/`));
await page.screenshot({path:`${out}/${topic}-${width}-${theme}-fullscreen.png`});
if(width<=700){await page.setViewportSize({width,height:480});assert(await panel.locator('dialog').evaluate(n=>n.scrollHeight>n.clientHeight));await panel.locator('dialog').evaluate(n=>n.scrollTop=n.scrollHeight);await page.screenshot({path:`${out}/${topic}-${width}-${theme}-short-bottom.png`});await page.setViewportSize({width,height:900});}
+28
View File
@@ -28,6 +28,34 @@ test('all sixteen metric definitions remain in the reference with explicit imple
for (const text of ['9 prototype calculations', '7 unimplemented metrics', 'no network collectors', '30 days', '12 months', 'below five people', 'Missing telemetry is unknown']) assert(page.includes(text), text);
});
test('two groups exhaustively classify the sixteen canonical contracts without duplication', () => {
const page = read('docs/strategy/measurement/index.mdx');
const manifest = JSON.parse(read('research/ai-adoption/measurement-migration.json'));
assert.deepEqual([...page.matchAll(/^### (.+)$/gm)].map(m => m[1]), ['Workflow effectiveness', 'Skills effectiveness & health']);
const rows = [...page.matchAll(/^\d+\. \[([^\]]+)\]\(\.\/([^/]+)\.mdx\) — \*\*(Prototype calculation|Unimplemented metric)\.\*\*/gm)];
assert.equal(rows.length, 16);
assert.equal(new Set(rows.map(m => m[2])).size, 16);
assert.deepEqual(rows.map(m => m[1]).sort(), manifest.metrics.map(m => m.title).sort());
assert.equal(rows.filter(m => m[3] === 'Prototype calculation').length, 9);
assert.equal(rows.filter(m => m[3] === 'Unimplemented metric').length, 7);
const [workflow, skills] = page.split('### Workflow effectiveness')[1].split('### Skills effectiveness & health');
assert.equal([...workflow.matchAll(/^\d+\. /gm)].length, 11);
assert.equal([...skills.matchAll(/^\d+\. /gm)].length, 5);
for (const slug of ['validated-task-success', 'confirmed-policy-effects', 'cost-per-accepted-outcome', 'workflow-specific-business-acceptance']) assert(workflow.includes(`./${slug}.mdx`));
for (const slug of ['skill-selection-precision', 'skill-selection-recall', 'supported-bundle-coverage', 'approved-workflow-adoption', 'skills-within-substantive-review-window']) assert(skills.includes(`./${slug}.mdx`));
for (const marker of ['N/A, not zero', 'More adoption does not prove improved work', 'Before/after trends alone are not causal evidence', 'Sandbox/evaluation cases remain excluded']) assert(page.includes(marker), marker);
});
test('workflow task-success contract retains evaluation exclusions and explains conditional skill slices', () => {
const page = read('docs/strategy/measurement/validated-task-success.mdx');
assert.equal((page.match(/\| Expression \|/g) || []).length, 1);
for (const marker of ['sandbox/evaluation tasks', 'Overlapping skill slices must not be summed', 'remains excluded by this contract', 'does not introduce an implemented skill-evaluation metric', 'N/A, not a zero workflow success rate']) assert(page.includes(marker), marker);
for (const name of ['baseline', 'skills-adoption', 'skills-maintenance', 'stage-01-skills-adoption']) {
const text = read(`docs/strategy/${name}.mdx`);
if (name !== 'stage-01-skills-adoption') for (const group of ['Workflow effectiveness', 'Skills effectiveness & health']) assert(text.includes(group), name);
}
});
test('published pilot arithmetic matches the executable fixture, including partial cost', () => {
const page = read('docs/strategy/skills-adoption.mdx');
const fixture = JSON.parse(read('scripts/fixtures/ai-kpi-synthetic.json'));
+2 -2
View File
@@ -43,7 +43,7 @@ test('domain contracts retain human authority, honest measures and Delivery-firs
assert(text('quality').includes('Critical effect blocks'));
assert(text('adoption').includes('Delivery first')&&text('adoption').includes('Later order undecided'));
assert(text('adoption').includes('No quotas or rankings'));
for(const marker of ['Available choices','16 candidate contracts','No mandatory collection','Meaning + applicability','9 prototype / 7 unimplemented'])assert(text('measurement').includes(marker),marker);
for(const marker of ['Workflow effectiveness','Skills effectiveness & health','16 optional candidate contracts','No mandatory collection','Before / after is not causality','9 prototype / 7 unimplemented'])assert(text('measurement').includes(marker),marker);
assert(text('maintenance').includes('No automatic reinstatement'));
});
test('topic compositions explain distinct relationships rather than a fixed card count',()=>{
@@ -55,7 +55,7 @@ test('topic compositions explain distinct relationships rather than a fixed card
has(g,'approve','owner');has(g,'distribute','withdraw');
const q=spec('quality');for(const id of ['selection','safety','artifact','outcome'])has(q,id,'gate');has(q,'gate','accept');has(q,'gate','rework');
const a=spec('adoption');for(const [x,y] of [['human','agent'],['agent','human'],['agent','learn'],['learn','delivery'],['learn','expand'],['human','expand']])has(a,x,y);
const m=spec('measurement');for(const id of ['qualification','outcomes','experience','health']){has(m,'registry',id);has(m,id,'contract');}
const m=spec('measurement');for(const [x,y] of [['workflow','compare'],['compare','interpret'],['skills','observe'],['observe','improve'],['interpret','improve']])has(m,x,y);
const b=spec('baseline');for(const [x,y] of [['workflow','selection'],['selection','evidence'],['evidence','position'],['position','comparison']])has(b,x,y);
const c=spec('maintenance');for(const [x,y] of [['observe','triage'],['triage','change'],['change','validate'],['validate','release'],['release','observe'],['triage','safe'],['safe','observe'],['triage','retire'],['triage','contain'],['contain','change']])has(c,x,y);
});