fix: optimize digital-twin through three SkillOpt epochs (#327)

Signed-off-by: Magnus Hedemark <magnus919@pm.me>

digital-twin/SKILL.md

@@ -24,14 +24,49 @@ For this skill, use these working distinctions:
 
 - **Digital model:** representation without a required live synchronization loop.
 - **Digital shadow:** observable flow from original to representation without a governed return path.
-- **Digital twin:** a versioned representation of a named entity or process, synchronized at an explicit frequency and fidelity, with models/services that support a declared decision or action.
+- **Digital twin:** a versioned representation of a named entity or process, synchronized at an explicit frequency and fidelity, with models/services that support a declared decision or action and a governed feedback relationship to the original. If it is synchronized and useful but has no governed return path, call it a read-only twin or digital shadow rather than implying closed-loop authority.
 - **Digital thread:** provenance and lifecycle linkage across systems, artifacts, decisions, and outcomes. A thread is necessary for many twins but is not itself a twin.
 - **Twin universe:** a federation or composition of purpose-bounded twins with explicit identity, time, provenance, semantics, ownership, and authority boundaries.
 
 These are operational definitions, not claims of universal standards consensus. NIST IR 8356 explicitly notes that no single definition is agreed, while allowing abstract entities and processes as twin subjects.
 
+## Choose an operating mode
+
+| Situation | Start in | Evidence required before advancing |
+|---|---|---|
+| You only need inventory or explanation | Read-only | Identity, source map, freshness, provenance |
+| You need counterfactual exploration | Simulation | Pinned snapshot/model/scenario, isolation, uncertainty, teardown |
+| You need to compare recommendations without effects | Shadow | Independent outcome comparison, abstention, operator disagreement |
+| You need a reversible low-impact action | Supervised or bounded | Policy, scoped credentials, preconditions, rollback, reconciliation |
+| You need high-impact or irreversible action | Human-approved exception or do not automate | Close-to-execution approval, independent validation, emergency stop |
+
+Do not start in a higher-authority mode merely because the model is confident or the user calls the system a dark factory.
+
+## Choose an entry point
+
+| What you have now | Enter here | First question |
+|---|---|---|
+| A vague idea or proposed use case | Frame the use case | What original, decision, owner, and harm boundary are actually in scope? |
+| A graph, dashboard, or event feed | Classify the representation | Is this a model, shadow, emulator, or twin, and what is missing? |
+| A working twin with stale or conflicting state | Evaluate independently | Which health plane failed, and should authority downgrade to `hold`? |
+| A validated shadow recommendation | Govern the action path | What exact capability, precondition, rollback, and expiry are authorized? |
+| A retired or superseded original | Retire deliberately | Which consumers, credentials, evidence, and orphan paths remain? |
+
+Then follow the numbered workflow and load the matching reference in its navigation table.
+
 ## Operating workflow
 
+Load the matching reference before acting:
+
+| Decision | Load |
+|---|---|
+| Architecture or federation | `references/architecture.md` |
+| Event, identity, state, provenance, semantics, graph, model, or simulation | `references/implementation.md` |
+| VVUQ, health, drift, SLOs, or agent evaluation | `references/evaluation.md` |
+| Security, privacy, authority, or earned autonomy | `references/governance.md` |
+| Change, incident recovery, or retirement | `references/lifecycle.md` |
+| Source scope or standards comparison | `references/source-index.md` |
+
 1. **Frame the use case.** Name the original, decision, desired outcome, authoritative sources, update/fidelity requirement, operating domain, owner, risk tier, forbidden actions, and simpler alternatives.
 2. **Classify the representation.** Decide whether the artifact is a model, shadow, twin, emulator, simulator, or composite universe. Do not upgrade the label without evidence of synchronization, model credibility, and a governed feedback path.
 3. **Design the contracts.** Define stable identities, event envelopes, timestamps, schema versions, provenance, freshness, uncertainty, validity intervals, permissions, and action semantics.
@@ -43,16 +78,9 @@ These are operational definitions, not claims of universal standards consensus.
 9. **Operate and evolve.** Monitor freshness, loss, ordering, schema/topology drift, residuals, calibration, uncertainty, scenario gaps, platform SLOs, agent trajectories, authority, and outcome value. Revalidate after material changes.
 10. **Retire deliberately.** Revoke action authority, drain and migrate consumers, preserve required lineage, remove secrets and sensitive data under policy, mark endpoints retired, detect orphan calls, and verify no live workflow still depends on the twin.
 
-## Choose the right reference
+## Reference loading
 
-| Need | Read |
+The **Operating workflow** navigation table is canonical: load the matching reference there before acting. The same references remain directly addressable for deep dives: architecture, implementation, evaluation, governance, lifecycle, and source-index.
-|---|---|
-| Architecture and federation | `references/architecture.md` |
-| Data, identity, event, graph, model, and simulation implementation | `references/implementation.md` |
-| VVUQ, health planes, SLOs, drift, agent evaluation, and chaos tests | `references/evaluation.md` |
-| Security, privacy, decision rights, and earned autonomy | `references/governance.md` |
-| Growth, change, incident recovery, and decommissioning | `references/lifecycle.md` |
-| Standards, source boundaries, and further reading | `references/source-index.md` |
 
 ## Agentic software factory boundary
 
@@ -60,9 +88,20 @@ A software factory analogue maps repositories, revisions, requirements, builds,
 
 A dark factory is an authority state, not a twin type. More automation requires stronger independent validation, provenance, staged rollout, rollback, and accountable escalation. Do not equate high model confidence with authority.
 
+## Choose the artifact
+
+| User needs | Produce | Template/reference |
+|---|---|---|
+| Define a twin and its authority | Twin manifest | `templates/twin-manifest.yaml` + `references/architecture.md` |
+| Test fidelity, synchronization, or agent behavior | Evaluation plan | `templates/evaluation-plan.md` + `references/evaluation.md` |
+| Decide whether to grant or expand authority | Release evidence packet | `templates/release-evidence.md` + `references/governance.md` |
+| Change, recover, or retire a twin | Lifecycle record | `references/lifecycle.md` |
+
+Use the smallest artifact that answers the decision; do not create a twin universe when a bounded model, shadow, emulator, or ordinary observability record is sufficient.
+
 ## Minimum release packet
 
-Before granting non-read-only authority, preserve:
+Before granting any authority beyond read-only, preserve the following evidence packet. It is the release gate, not a suggestion:
 
 - intended-use, risk, and authority contract;
 - source and identity map;