control-register-authoring

Control Register Authoring

Use this skill to add or revise controls that appear in the site admin security workspace.

Workflow

1. Confirm the control exists in references/workspace-files.md under the NIST moderate source file before editing the generator.
2. Update references/workspace-files.md targets in this order:
   • scripts/compliance/generate-active-control-register.ts
   • only then regenerate compliance/generated/active-control-register.seed.json
   • update convex/security.ts only if site admin workspace materialization or reseed behavior must change
3. Keep the control readable to two audiences at once:
   • the internal site admin maintaining evidence
   • the customer security admin reviewing the control
4. Tie every checklist item to concrete repo evidence when available.
5. If repo support is partial, keep the checklist item and mark it partial or incomplete instead of overstating coverage.
6. Regenerate and reseed after changes.

Authoring Rules

• Start from the NIST control title and statement in the generated moderate controls JSON. Do not invent control IDs.
• Do not hand-edit compliance/generated/active-control-register.seed.json. Always regenerate it from the script.
• Prefer explicit csf20Ids and soc2CriterionIds overrides when the inherited crosswalk is broader than the app evidence actually supports.
• Keep implementation summaries narrow. Do not let one control drift into adjacent controls.
• Ensure the implementation summary is fully supportable by the checklist items and seeded evidence. If the checklist or evidence is narrower than the summary, narrow the summary.
• Write for a customer security admin first. The target reader should understand what the control does, what evidence exists, and what remains their responsibility without needing repo knowledge.
• Keep shared-responsibility wording precise:
  • platform items describe what the hosted service does
  • customer responsibility notes describe what the customer must govern or operate
  • provider-internal process items should be clearly labeled as provider or operator duties, not customer guidance
• Prefer explicit actor labels. Use Provider, Customer, Platform, Hosted service, or Site admin instead of ambiguous terms like operator unless the actor is immediately clarified.
• Evidence should point to concrete code, config, UI, or schema artifacts already in the repo.
• Evidence descriptions must read like artifact descriptions, not just conclusions and not just file-path notes.
• Seed evidence at the checklist-item level, not only at the control level.
• When evidence only proves part of the claim, set sufficiency to partial and keep the checklist status honest.
• Preserve stable control IDs and checklist item IDs so reseeds do not create logical duplicates.