Skip to content

Documentation Guidelines

This guide keeps SkillPilot documentation navigable as QA lanes, curriculum rollout notes, generated reports, and pilot dossiers grow.

Document Roles

Every documentation file should have one primary role.

Role Purpose Typical location Source of truth?
Concept Durable model, semantics, and design intent docs/concept/ Yes
Runbook Operational steps for a repeated workflow near the owning process doc Yes
Process Review rules, status meanings, and decision workflow docs/qa-ci/ or docs/dev/ Yes
Generated status Current computed report, queue, or dashboard artifact docs/qa-ci/status/ No
Pilot or dossier Dated investigation, initial PoC, remediation slice, or one-off evidence bundle docs/qa-ci/archive/, docs/qa-ci/status/, or docs/dev/ No, unless explicitly stated
Implementation note Developer-facing design or migration detail docs/dev/ Sometimes

If a document starts mixing roles, split it before adding more content.

Placement Rules

  • Put durable graph, didactic, runtime, and ontology concepts under docs/concept/.
  • Put QA process contracts, review-lane semantics, and CI rule explanations under docs/qa-ci/.
  • Put generated QA snapshots under docs/qa-ci/status/.
  • Put dated QA investigations under docs/qa-ci/archive/ once they are no longer the current runbook.
  • Put implementation plans, migration notes, and developer-only audits under docs/dev/.
  • Keep temporary experiments out of docs/; use tmp/.

Generated Files

Generated Markdown files should start with a clear notice:

> Generated artifact. Do not edit manually.
>
> Generated by: `<script>`
> Regenerate with: `<command>`
> Source of truth: `<config-or-ledger>`

Generated files may contain useful human-readable status, but decisions belong in the configured source files, ledgers, mappings, or code that generate them.

Registered generated Markdown files are checked with:

cd app
npm run check:generated-doc-notices

When migrating another generated report to this notice format, add it to app/scripts/generatedMarkdownNoticeRegistry.ts in the same change.

Generated QA status artifacts are also rendered into docs/qa-ci/status/README.md from app/scripts/generatedMarkdownNoticeRegistry.ts. Add new generated status outputs there with their role, source of truth, and regeneration command, then run:

cd app
npm run docs:generated-status-registry
npm run check:generated-status-registry

QA Lane Template

Use this structure for durable QA lane docs:

# <Lane Name>

## Purpose
## Source Of Truth
## Generated Artifacts
## Run
## Blocking Semantics
## Review Ledger
## Review Workflow
## Expansion Criteria
## Related Documents

Keep current counts, sampled findings, and dated investigation notes out of the durable lane doc. Put them in a generated status artifact or an archive/pilot record.

Runbook Template

Use this structure for operational runbooks:

# <Lane Name> Runbook

## Run The Audit
## Inspect Results
## Decide Or Fix An Item
## Interpret Diagnostics
## Verify Local Changes

Runbooks should be short and command-focused. They can link to process docs for semantics instead of restating them.

Pilot And Archive Rules

  • Date PoC records in the filename, for example mem-sparql-consistency-poc-2026-06-01.md.
  • Keep baseline numbers and historical interpretations in the dated record, not in the durable process doc.
  • If an old public link exists, keep a compatibility pointer rather than deleting the file.
  • Archive records should say whether they are historical evidence, current process, or source of truth.

Before finishing documentation changes:

git diff --check

Run the repository Markdown link check:

cd app
npm run check:docs-links
npm run check:docs-indexes

check:docs-indexes currently requires every covered Markdown file to be linked from the corresponding index.md. It covers docs/concept/ recursively and the direct Markdown children of docs/deploy/, docs/dev/, docs/production-pipelines/, docs/qa-ci/, docs/quickstart/, docs/security/, and docs/whitepaper/.

For docs that reference generated JSON, also parse the JSON source files:

node -e "JSON.parse(require('fs').readFileSync('docs/qa-ci/status/curriculum-quality-status.json','utf8')); console.log('json ok')"