Sparkore Core

View saved version →

---
name: balance-analysis
description: Use for the receiving project's balance modeling, audits, calibration, scenario comparison, pass generation, or validation across Weapon, Hero, Equipment, Enemy, progression, economy, and player-loadout power.
---

# Balance Analysis Skill

Apply the [receiving-project contract](../../references/project-context.md). Resolve the actual game systems, configuration owner, active balance phase, and promotion gates from the project; the domains listed in the description are examples.

## Goal
Produce traceable, non-destructive balance decisions from explicit scenarios, formulas, assumptions, evidence tiers, and exit gates without confusing configured values, model outputs, runtime behavior, and final accepted balance.

## Trigger
Use for balance design/modeling, quantitative audits, pass comparisons, calibration, target budgets, TTK/DPS analysis, or validation. Activate `knowledge-steward` when durable KB state changes and `runtime-audit` when code/runtime semantics must be verified.

## Authority boundaries
- Balance process, methodology, accepted design intent, exit gates → canonical balance docs/roadmap.
- Structured config and live numeric values → the project's designated live configuration, Sheets, or CSV (for example, a project may use `BlueprintData`).
- Experimental calculations/workbooks → designated balance workbooks; they are evidence/work artifacts, not automatic canonical truth.
- Implemented runtime behavior → the designated repository/runtime evidence.
- Playtest observations → designated playtest logs.
- Production outcomes → the project's designated analytics source.

## Core loop
1. Define the exact balance question, player experience, scenario, and metric.
2. Lock the test boundary; avoid changing unrelated variable families at the same time.
3. State formulas, units, assumptions, expected ranges, confidence, and provisional dependencies.
4. Preserve accepted sources; create non-destructive variants/passes for experiments.
5. Validate data integrity before interpreting outputs.
6. Use the highest available evidence tier: config/formula → code/runtime semantics → controlled test → loadout/encounter test → structured playtest → production telemetry.
7. Compare model with evidence and separate model error, implementation error, and tuning error.
8. Decide: accept, revise, reject, or keep temporary.
9. Promote structured values only after the relevant exit gate is explicitly accepted.
10. Persist durable methodology/decisions and update compact context/working state without copying whole workbooks into the KB.

## Scenario discipline
- Never present a scalar as final Player/Hero/Equipment Power unless that model is explicitly assigned and accepted.
- Preserve scenario names and reference fixtures so comparisons remain reproducible.
- State occupied-cell/spatial assumptions when backpack opportunity cost matters.
- Separate direct stat contribution from ability/passive/behavior realization when evidence differs.
- Label inherited provisional baselines; downstream calculations do not upgrade their evidence quality automatically.

## Output discipline
A canonical balance artifact should make clear: question, scope/exclusions, source ownership, scenario fixtures, formulas/evaluation order, assumptions/confidence, evidence tier, findings, accepted decision or temporary decision, exit/revisit trigger, and links to numeric workbooks/config.

Large matrices and live numeric tables stay in their owned workbook/config. The KB stores interpretation, methodology, constraints, and accepted decisions.

## Current project process
Follow the receiving project's active balance roadmap, deferred gates, evidence ladder, and non-destructive-pass rules. The source project's `Game Balance Roadmap.md`, numeric fixtures, and M4/M5 milestones remain project-owned; they are not prerequisites or default state for another game.

Referenced files: 1

View saved version →

---
name: game-project-planner
description: Build or revise a game Project Plan spreadsheet from a project brief, feature backlog, team capacity and delivery goals. Use for Feature List review and milestone planning; not for detailed GDD authoring or publisher operations unless explicitly in scope.
---

# Game Project Planner

## Purpose and portability

Turn a game concept or existing feature list into a concise product backlog and an executable milestone plan. Migrated into Sparkore's shared plugin from the source KB; no source project's design, staffing, technology, or scope is a default for another project. Apply the [receiving-project contract](../../references/project-context.md) when resolving project context and ownership.

Install or move the whole `sparkore-core` plugin, preserving its `skills/` and shared `references/` directories. This skill folder alone is not a standalone distribution: its receiving-project contract lives outside the folder. Keep each project's facts in its own brief and spreadsheet; do not edit this skill to store a project's timeline or feature list. Follow the receiving project's agent guide and writing policy. Discuss with the owner in their preferred language; confirm the spreadsheet language.

## Start with the relevant mode

- New plan: read [Discovery questions](references/discovery.md), extract known answers, then ask only consequential unanswered questions.
- Existing plan: first read live tab names, headers, values, notes, merges, formatting and validation. User edits and current decisions take precedence over remembered row numbers or previous assistant proposals.
- Review only: return findings and proposed changes without writing.
- Authorized update: make the scoped changes and verify them; do not repeat approval questions already answered.

Use the available spreadsheet capability for implementation. For native Google Sheets, preserve native structure and use live reads before edits. Do not rely on a particular connector being installed; state an access limitation if the requested destination is unavailable, and do not claim a draft was uploaded.

## Establish a planning brief

Resolve the product loop, target platform, delivery endpoint, player-experience horizon, responsibility boundary, team availability, reusable dependencies, time basis and destination. Compile a short brief including accepted facts, open decisions, assumptions, proposed sections and sheet schema.

For new or materially ambiguous plans, show this concrete brief before a substantial workbook rewrite. Existing explicit approval is sufficient; ask only for unresolved decisions that materially change scope or authority. Do not make the questionnaire a mandatory interview when the brief is already complete.

## Build the Feature List

Use [Spreadsheet contract](references/spreadsheet-contract.md). Treat the list as a product backlog, not an implementation task inventory.

- Identify the core playable loop and supporting progression/content/UI systems before adding secondary layers.
- Use genre-appropriate coverage prompts: controls/combat, session lifecycle, game modes, progression, economy, content, onboarding, player settings, retention, monetization and in-game service integration. These are prompts, not mandatory features or fixed section names.
- Distinguish a game capability from an implementation/QA task and from an external team's deliverable. A production team can own game-side integration without owning an admin console, marketing campaign, customer support workflow or shared publishing platform.
- Preserve owner-defined sections and names. Consolidate overlap through an explicit scoped change, not by silently deleting a feature or reintroducing a rejected feature under another name.
- Assign or preserve priority independently of delivery status. Priority does not mean a feature has been approved for the current release.
- Audit dependency chains, including reward producers and consumers: shops/gacha must have usable outputs; recycle resources need an applicable sink; FTUE must follow the system being taught.
- Do not silently rewrite accepted descriptions to repair a design contradiction. Record the proposal or ask for a decision. When descriptions are blank and drafting is authorized, fill concise descriptions directly. Put proposed replacements for existing descriptions in notes unless the owner authorizes promotion.

## Build the Milestone Plan

Choose milestones by testable product maturity and dependencies, not a fixed number or naming scheme. Break a feature into Function rows only when it needs smaller deliverables. Repeated appearances must describe different increments, integration or validation, not duplicate full implementation.

Estimate from role capacity: people, seniority, effective availability, reuse, dependencies, design/art lead time, integration, QA and rework. Do not count a PO who also performs QA as two full-time people. If part-time hours are unknown, label the estimate provisional; do not invent an FTE value or unavailable specialist. Capture capacity assumptions compactly with the schedule rather than expanding the backlog.

An illustrative calculation is available person-weeks = people × weeks × agreed availability. Apply an explicit allowance for non-feature work when useful; no fixed percentage is mandatory. Check bottlenecks by role, not only aggregate headcount. If a deadline and scope conflict, propose concrete scope/resource/timeline choices.

Each milestone needs a short name, start/end period, duration, one Objective and a few measurable Key Results. Distinguish proposed targets from measured evidence. Keep names stable for dropdown references; place timing in the OKR column by default.

Planning through soft launch does not imply waiting for a D30 cohort. Prepare the D30 journey, content, replay goals and economy before launch; actual D30 retention is a later observation unless explicitly in scope. If production owns only handoff, the endpoint is a testable build handoff, not store approval or rollout owned by another team. Shared modules are named dependencies with an owner/interface and required availability, not assumed finished systems.

Account for every retained backlog item as planned or explicitly unplanned. Do not create a Backlog milestone. Reconcile changes in both sheets without adding a deferred feature into the committed scope merely to hide an unresolved dependency.

## Revise and finish

On revisions, preserve unrelated edits, notes, formulas, status values and native controls. Re-read before index-sensitive deletes and resolve duplicate names through Section/Feature/Function or an existing ID. A red priority cell is not an instruction to delete a row: use the owner's marking convention and inspect explicit formatting.

Run [Acceptance checks](references/acceptance.md). Report the destination, actual changes, planned/unplanned coverage, material assumptions and any verification limitation. Do not claim native multi-select behavior or visual fit from display text alone.

Referenced files: 4

View saved version →

---
name: gdd-authoring
description: Create a new GDD or substantially revise a canonical game-design document with explicit rules, source ownership, evidence, and review gates.
---

# GDD Authoring Skill

Apply the [receiving-project contract](../../references/project-context.md). For substantial authoring, load the bundled [authoring standard](../../references/gdd-authoring-standard.md); use [templates](../../references/gdd-templates.md) for document structure and the [review checklist](../../references/gdd-review-checklist.md) before publication. Apply the receiving project's explicit policy where it differs.

## Goal
Produce canonical GDDs that are simultaneously readable by humans and reliably interpretable by AI agents, while keeping live numeric/config data and final visual assets in their designated owners.

## Trigger
Use for new GDDs or substantial GDD rewrites. For legacy-source migration, also activate `gdd-migration`. For any durable KB write, also apply `knowledge-steward`.

## Authoring principles
- One canonical owner per durable rule.
- Current design first; history belongs in decisions/archive.
- Separate design intent from runtime observations.
- Keep large/live numeric tables in designated Sheets/CSV; explain meaning, relationships, formulas, methodology, and intent in the GDD.
- Use progressive disclosure: orientation → normative design → evidence/operations.
- Essential meaning must remain understandable in text/structured form even when external visuals are unavailable.
- Unknowns remain explicitly unknown; do not smooth them into confident prose.

## Required workflow
1. Read the available project guide, current state and relevant domain context resolved through the receiving-project contract; load `knowledge-steward` once when writing durable knowledge.
2. Identify the canonical owner and scope. Avoid creating a new note if an existing canonical note already owns the concept.
3. Discover only the minimum source set needed: canonical KB, designated config, exact Figma frames, code/runtime evidence, analytics, or legacy material as applicable.
4. Separate accepted design facts, runtime observations, proposals, temporary assumptions, and open questions.
5. Map the intended content and artifacts to existing explicit approval. A complete approved brief or scoped update request is sufficient; do not require a new confirmation pack merely because the write is substantial. If material decisions or authority remain unresolved, consolidate those questions, recommended resolutions, assumptions and affected artifacts for the owner.
6. Write the authorized final state directly. Ask only about unresolved material decisions or a material departure from approved scope; use `review` for an actual unresolved checkpoint.
7. Apply required metadata and consistent terminology.
8. Add tables/diagrams/formulas only when they reduce ambiguity or reading time; do not force visuals.
9. Link external sources with explicit ownership meaning rather than copying volatile data.
10. Run the GDD review gate, read back all changed artifacts, then update context/index/state only when their current-state meaning changes.

## Document structure
Use sections as applicable:
- **Layer 1 — Orientation:** summary, player experience/design goal, scope/exclusions, at-a-glance facts, compact overview visual when justified.
- **Layer 2 — Normative design:** core rules, states/flow, inputs/conditions/outputs/failure handling, formulas, interactions/dependencies, edge cases.
- **Layer 3 — Evidence and operations:** structured-config ownership, exact Figma references, repo/runtime paths and drift, analytics/acceptance criteria, open questions and validation state.

## Metadata baseline
Use compatible YAML frontmatter for substantial new/reworked GDDs with `type`, `project`, `domain`, `feature`, `status`, `canonical`, `owner`, `validation`, `last_reviewed`, and optional `review_after`. Lifecycle state and evidence quality are independent.

## Visual and formula rules
Use Markdown tables for exact mappings, Mermaid for compact rule/state flows, charts generated from owned source data for trends, exact Figma frames for UI layout/prototypes, and owned visual references for art/VFX. Never encode essential meaning only through a visual. Define variables/units and evaluation order for non-trivial formulas and include a worked example when useful.

## Activation gate
A GDD may become `active` when material conflicts are resolved or excluded, design rules are separated from runtime observations, required source/visual context is present, essential behavior is understandable without hidden external context, owner approval exists for the approved scope, and changed artifacts pass readback.

## Project standards
The bundled references preserve the original reusable authoring workflow. If the receiving project maintains active local standards, reconcile differences against its agent guide and source-of-truth policy; installing the plugin does not silently replace those project standards.

Referenced files: 1

View saved version →

---
name: gdd-migration
description: Use when migrating legacy, fragmented, Figma-based, spreadsheet-based, or otherwise non-canonical game-design material into the receiving project's canonical KB.
---

# GDD Migration Skill

Apply the [receiving-project contract](../../references/project-context.md). Use the [migration brief and confirmation templates](../../references/gdd-templates.md) and [review checklist](../../references/gdd-review-checklist.md) when preparing publication.

## Goal
Migrate one bounded feature/system at a time into a clear canonical GDD without creating competing sources of truth or repeatedly re-reading entire legacy source sets.

## Trigger
Use for legacy GDD migration or consolidation of fragmented design sources. Also activate `knowledge-steward` and `gdd-authoring` when publishing or substantially rewriting canonical GDD content.

## Source routing
- Design intent, gameplay rules, formulas, states, conditions, edge cases, accepted decisions → canonical KB.
- Large numeric/config tables → the designated structured data/config source; link and explain meaning, do not duplicate.
- UI layout, wireframe, prototype, spatial visual flows → the designated visual-design source (for example, Figma); migrate behavioral rules and link exact frames.
- Implemented behavior/schema → the designated repository/runtime evidence; report drift against design.
- Analytics data → the designated analytics source; document definitions/usage, not raw data.
- Obsolete migrated material → archive/deprecate with replacement link; do not silently delete historical evidence.

## Required workflow
1. Define the migration brief: feature boundary, goal, exclusions, owner/reviewers, source list, known conflicts, target canonical owner.
2. Inventory source structure once. For Figma, record exact page/frame/node references and revisit only frames relevant to the current batch.
3. Extract atomic claims: intent, rule, state/transition, condition/outcome, formula meaning, edge case, UI behavior, config reference, runtime observation, decision/proposal/open question.
4. Classify every claim by knowledge state and destination.
5. Reconcile conflicts explicitly. If authority is unresolved, block that claim from canonical publication rather than guessing.
6. Match the migration scope and target artifacts to existing explicit approval. Reuse an approved brief or scoped migration request. If material conflicts or decisions remain, consolidate only the unresolved facts/questions, recommendations, assumptions and affected artifacts for confirmation.
7. Publish within that authorized scope once; do not require a new approval round for an already approved migration. Return only material departures or unresolved decisions to the owner. Update ownership/index/decision records only where materially needed.
8. Deprecate/archive superseded legacy material without deleting required evidence.
9. Read back all changed artifacts and verify links, metadata, ownership, and unresolved follow-up work.

## Efficiency rules
- Migration unit is one bounded feature/system, not an entire Figma file or legacy corpus.
- Inventory broadly once; then read narrowly.
- Do not re-read legacy material already compiled into an active canonical GDD unless validation/conflict investigation requires it.
- Prefer updating an existing canonical owner over creating another note.
- Keep a phase tracker only for long migrations; completed trackers move out of the active path.

## Definition of Done
A migration is complete when one canonical owner exists, relevant legacy sources were inventoried, durable claims were routed correctly, conflicts are resolved or explicitly open, external source ownership is linked correctly, significant accepted decisions are persisted, legacy material is deprecated/archive-routed as appropriate, owner approval is recorded, and changed artifacts pass readback.

## Project migration state
Use any active migration SOP and tracker designated by the receiving project. The source KB's legacy `GDD Migration SOP.md` was not present in the migration snapshot; this package does not claim to include it. The operational workflow here and bundled templates/checklist are available without that file. Resolve any project-specific migration gate from current project guidance.

Referenced files: 1

View saved version →

---
name: kb-bootstrap
description: Initialize a project knowledge base shared by Codex and Claude Code, or onboard an existing KB to shared agent guidance, canonical-source routing and handoffs. Use when asked to set up the KB; not to scaffold game code, infrastructure or accounts.
---

# KB Bootstrap

Create a small, usable project KB with one set of operating rules and durable
work state. The shared plugin supplies methods; the receiving KB owns facts,
local policy, decisions and progress. Apply the
[receiving-project contract](../../references/project-context.md) and the
[Knowledge Steward](../knowledge-steward/SKILL.md) for durable writes.

## Establish the target

Resolve the KB location, project name, owner when known, existing content and
the first work objective. Reuse supplied answers. Ask only for missing choices
that change where or what to write. Keep an unknown product brief or unavailable
source explicitly unknown; neither blocks creating the authorized KB structure.
Use the project's language policy; otherwise canonical notes use English and
conversation uses the user's language.

Inspect the target before writing. A new empty KB can use the bundled starter.
An existing KB needs mapped ownership and a scoped adoption plan, not a second
taxonomy. A setup request authorizes its routine KB writes; do not repeatedly
ask for approval already given. Do not invent design decisions or approve a
product direction as a side effect of setup.

## Create or adopt

Read [setup and handoff guidance](references/setup.md) for the output contract,
existing-KB route and Codex/Claude setup checks.

For an empty local directory, use the create-only
[bootstrap helper](scripts/bootstrap_kb.py). Resolve its installed path; the
following locations are placeholders:

```sh
python3 /installed/kb-bootstrap/scripts/bootstrap_kb.py /target/KB --project "Project name" --owner "Project owner"
python3 /installed/kb-bootstrap/scripts/bootstrap_kb.py /target/KB --project "Project name" --owner "Project owner" --apply
python3 /installed/kb-bootstrap/scripts/bootstrap_kb.py /target/KB --project "Project name" --check
```

The first command previews without writes. `--apply` creates missing files only;
it preserves existing files on a recognized rerun and refuses a foreign nonempty
directory. `--check` verifies starter structure, not semantic or host readiness.
It requires only Python 3.9+; lint has its own declared dependencies.
Pass a supplied first work objective with `--objective "..."` in both preview and
apply so it is persisted in the initial brief/checkpoint before later enrichment.

Read the generated notes and adapt the brief, sources and first checkpoint from
actual user information. Add only the first needed domain and its context when
there is durable content to own; do not manufacture empty game-system folders.
The helper deliberately does not infer facts from its project-name argument.

Keep `AGENTS.md` as the shared operating guide. For a new KB, `CLAUDE.md` imports
that guide rather than maintaining another policy. Use host skill discovery for
the installed Sparkore workflows; never write a user's cache path into the KB
or copy plugin skills into it. Preserve meaningful existing host instructions
when adopting a KB and reconcile conflicts explicitly.

When Python/local filesystem access is unavailable, create the same logical
artifacts through the available file tools or return the exact unperformed work.
Do not claim script execution, local sync or host discovery without observing it.

## Verify and hand off

- Read back changed files and verify source ownership and local links.
- Run the starter structure check when using the helper, then the installed
  [KB Maintenance](../kb-maintenance/SKILL.md) lint with the KB root/profile.
  Inspect coverage; no decisions in a new KB is normal, not an audit of decisions.
- Test the available host's startup route using only the KB artifacts: find the
  current objective, next action, owner and relevant workflow without chat history.
- Exercise an authorized durable update and update the work checkpoint; confirm
  another agent can read the resulting state. Shared storage is not a file lock:
  overlapping writes must be serialized through the work record's ownership.
- Record bootstrap, lint, semantic-route and actual host checks separately in the
  setup work note. Missing Claude Code execution stays untested; a link check is
  not a Claude session. Finish with the usable KB location, next task and gaps.

Only configure KB files. Engine projects, Git remotes, cloud storage, sync clients,
credentials, app permissions and plugin installation are outside this workflow
unless separately requested. Installing a plugin alone does not run bootstrap.

Referenced files: 17

View saved version →

---
name: kb-maintenance
description: Use for the receiving project's KB linting, stale-content review, context refresh, lifecycle hygiene, contradiction/duplication audits, archival, and safe cleanup.
---

# KB Maintenance Skill

Apply the [receiving-project contract](../../references/project-context.md) for project paths, authority, companion skills, and the lint script's supported layout.

## Goal
Keep the active knowledge surface small, current, coherent, and cheap for agents to load while preserving historical rationale outside the default retrieval path.

## Trigger
Use for periodic maintenance, milestone-exit hygiene, stale-context review, archive/supersede work, decision cleanup, or KB quality audits. Also run after major migrations, balance phase exits, architecture changes, large decision growth, or long multi-session work series.

## Maintenance modes
### Light hygiene
Run frequently or at major task boundaries:
- broken links
- missing/invalid metadata
- duplicate IDs
- stale active Work state
- expired `review_after`
- active indexes pointing to superseded/archived owners
- missing replacement links
- obvious orphan context/index files

### Deep hygiene
Run at milestones or periodically:
- semantic contradictions
- duplicated canonical concepts
- long-lived temporary decisions
- stale `_Context.md` versus canonical docs
- completed work still in active paths
- obsolete migration/audit artifacts
- Source-of-Truth ownership drift
- oversized operational monoliths that should be indexed/split

## Hot/Warm/Cold policy
Maintenance protects progressive disclosure:
- Hot = root agent guide, project state, relevant domain context.
- Warm = triggered skills, active canonical docs, active decisions/work.
- Cold = legacy/superseded/history/research/archive.

Superseded or archived material must not leak into Hot/active indexes unless explicitly referenced for history.

## Action policy
- **Retain:** historically valuable decisions, major audits, final validations.
- **Archive:** completed trackers, stale working-state snapshots, superseded methodologies, historical snapshots.
- **Delete:** only clear duplicates, empty/stub notes, accidental copies, or disposable intermediates whose unique content is already compiled elsewhere.

Ambiguous destructive deletion requires owner approval.

## Deterministic-first rule
Mechanical checks should be implemented in scripts when possible, e.g. `kb_lint.py`, rather than repeatedly asking an LLM to reason about them. LLM reasoning is reserved for semantic contradiction, duplicate meaning, staleness, merge/split decisions, and lifecycle judgment.

### Current lint script
Read [runtime and project profiles](references/linting.md) before the first run. Resolve this installed skill's [lint script](scripts/kb_lint.py), use Python 3.9+ with its [runtime dependencies](requirements.txt), and pass the receiving vault root explicitly. The following paths are placeholders to replace with those resolved locations:

```bash
python3 "/absolute/path/to/installed/kb-maintenance/scripts/kb_lint.py" "/absolute/path/to/target-vault"
```

Use `--json` for machine-readable output and `--stale-work-days N` to change the default 30-day Work staleness threshold. Select the project's `.kb-lint.json` or pass `--config` with an explicit profile. For audit-only tasks, use an existing profile or a temporary one rather than writing new project configuration. Inspect reported settings, matched files and skipped checks before claiming coverage; zero matching files or exit code 0 alone is not a clean audit.

The script checks YAML metadata/lifecycle, local Markdown links and wikilinks, duplicate decision definitions, current canonical ownership, expired review dates, stale active Work, archive links, replacement metadata and context orphans under the selected conventions. A clean mechanical lint does not replace semantic review. If Python/dependencies are unavailable, state the limitation and continue only the checks the host can actually perform.

## Maintenance output
Produce a compact report grouped by: automatic-safe fixes, archive/supersede candidates, semantic-review candidates, destructive-delete candidates requiring approval, context/index refreshes, and unresolved ownership conflicts.

After accepted maintenance, rebuild affected indexes/context, read back changed artifacts, and ensure `PROJECT_STATE.md` remains compact rather than becoming a maintenance log.

Referenced files: 4

View saved version →

---
name: knowledge-steward
description: Use whenever creating, editing, migrating, reorganizing, superseding, archiving, or otherwise changing durable knowledge in the receiving project's knowledge base.
---

# Knowledge Steward Skill

## Goal
Keep the receiving project's knowledge current, non-contradictory, traceable, portable across AI agents, and cheap to load. Persist durable project truth in canonical project artifacts instead of relying on chat history or assistant memory.

Apply the [receiving-project contract](../../references/project-context.md) when resolving paths, authority, language, and companion skills.

## Trigger
Activate this skill when a task will change durable KB knowledge, governance, lifecycle, indexes, context, decisions, backlog, or work-state artifacts. Do not activate merely to answer a transient question that causes no durable KB change.

## Core rules
1. Source of Truth over chat history.
2. Discussion is not a decision.
3. Confirmed durable decisions are persisted.
4. One canonical home per fact; link instead of copying.
5. Current-state notes contain current truth, not accumulated history.
6. Preserve historical rationale without preserving contradictions in active context.
7. Structured/numeric data stays in its designated live source; KB stores meaning, intent, methodology, assumptions, constraints, and accepted decisions.
8. Prefer updating an existing canonical owner over creating a competing note.
9. Keep lifecycle state separate from evidence/validation state.
10. Read the minimum sufficient context; expand only when uncertainty or validation requires it.

## Required workflow
1. Read the receiving project's available agent guide and current-state artifact if not already loaded; use the equivalents resolved by the project contract.
2. Identify the task domain and read its available context/index. Missing source-KB filenames do not require creating a new taxonomy.
3. Determine the canonical owner using the project's Source of Truth or relevant domain index. Use the bundled [authority reference](../../references/source-of-truth.md) for reusable distinctions when no project equivalent exists.
4. Read only the canonical notes needed for the change.
5. Classify incoming information as discussion, proposal, decision, temporary decision, open question, deprecated, or superseded.
6. For a substantial or ambiguous write, consolidate material facts, decisions, trade-offs, temporary assumptions, unresolved blockers, and exact artifacts to be changed before writing. Obtain owner confirmation when required by scope or uncertainty.
7. Update the smallest canonical artifact set once using the accepted final state.
8. Add/update a durable decision record only when rationale/history has future value; routine edits do not require one.
9. When replacing an older decision or document, mark it superseded/deprecated and point to the replacement; remove it from active/default indexes.
10. Update relevant `_Context.md`, `PROJECT_STATE.md`, active Work state, backlog, and indexes only when their current-state meaning changes.
11. Read back every changed artifact.
12. Run deterministic validation/lint when available.
13. Report what changed and any remaining uncertainty or revisit trigger.

## Context discipline
Default loading order is Hot → Warm → Cold.

**Hot:** `AGENTS.md`, `PROJECT_STATE.md`, relevant domain `_Context.md`.

**Warm:** triggered skills, active canonical GDD/technical docs, active decisions, active work state.

**Cold:** legacy GDD, superseded decisions, historical audits, completed work/session artifacts, raw research, `99_Archive/`.

Never scan Cold knowledge by default. Access it only for migration, history/rationale recovery, conflict investigation, evidence verification, or explicit audit.

## Lifecycle and cleanup
Canonical documents may use `draft`, `review`, `active`, `temporary`, `deprecated`, `superseded`, `archived`. Validation/evidence state is separate. A `review_after` date triggers maintenance review; it does not automatically invalidate a document.

Prefer retain/supersede/archive when historical value exists. Destructive deletion is appropriate only for clear duplicates, empty/stub notes, accidental copies, or intermediate artifacts whose unique evidence/rationale has already been compiled into a canonical owner. Ambiguous destructive deletion requires owner approval.

## Working-state rule
Long or multi-session work must maintain a compact working-state artifact with: goal, completed work, confirmed decisions, current findings, changed artifacts, open issues/blockers, next step. When work completes, move it out of the active path.

## Language
Follow the receiving project's writing policy; default to English for canonical knowledge and the user's language for conversation. Preserve exact IDs, code/config identifiers, paths, and localized player-facing strings when relevant.

## Project governance
This packaged skill supplies the operational method. The receiving project's agent guide and active governance records own local policy and migration state. If a legacy Knowledge Steward document is still active there, reconcile it against that authority rather than assuming it was retired by installing this plugin.

Referenced files: 1

View saved version →

---
name: runtime-audit
description: Verify or reconcile canonical game design against code, designated live configuration, synced CSV, builds, logs, and runtime evidence.
---

# Runtime Audit Skill

Apply the [receiving-project contract](../../references/project-context.md) to resolve canonical sources, project paths, and companion skills.

## Goal
Verify what the game actually does without silently converting implementation evidence into design intent, and surface actionable drift between canonical design, structured config, release artifacts, and runtime behavior.

## Trigger
Use for code inspection, config/runtime verification, mapping checks, implementation audits, build/test evidence, or design↔runtime reconciliation. Activate `knowledge-steward` when findings change durable KB knowledge.

## Evidence roles
- Canonical KB → accepted design intent/rules.
- Designated live configuration (for example, `BlueprintData` in a project that uses it) → current structured configuration used by the game; proves configured values, not final design/balance approval.
- Synced repository CSV → release-build artifact expected to match an approved Sheet snapshot; mismatch is a sync observation unless another owner establishes a design defect.
- The designated repository/code → implemented behavior and schemas.
- Build/log/test → observed runtime behavior for the tested version/environment.

## Required workflow
1. Read the available project guide, current state and relevant domain context resolved through the receiving-project contract, then the smallest canonical document set.
2. State the exact audit question and expected canonical behavior.
3. Read only the code/config paths required to answer it; avoid broad repository scans unless dependency discovery requires expansion.
4. Capture exact evidence: file/path, class/method/system, config table/row/field, build/test version, or log reference as applicable.
5. Classify each finding as `Matches design`, `Config drift`, `Implementation drift`, `Unspecified runtime behavior`, `Design ambiguity`, or `Validation gap`.
6. Do not silently choose a winner when sources conflict. Apply Source-of-Truth ownership and surface unresolved intent to the owner.
7. Distinguish a runtime defect from an outdated GDD, provisional config, release-sync issue, or intentionally deferred implementation.
8. For approved corrections, update the smallest authoritative source(s), then read back and record any remaining validation requirement.

## Audit report minimum
Include question, canonical expectation, evidence locations, observed behavior/config, classification, impact, recommended owner/action, confidence/evidence level, and whether the finding changes current `_Context.md` or `PROJECT_STATE.md`.

## Safety against re-derivation
Once a verified runtime semantic has been compiled into an active canonical/current-state artifact, do not re-audit it on every task. Reopen code/config when the implementation changed, evidence is stale/uncertain, a conflict appears, or the task explicitly requires verification.

Referenced files: 1