scope-knowledge-update

name	scope-knowledge-update
description	Use after SCOPE evidence review, final disposition, or operator-approved save to update durable environment knowledge, observations, coverage gaps, or proposed reasoning-note improvements.

SCOPE Knowledge Update

Use this skill after a top-level agent has evidence-backed results and the operator-approved workflow allows persistence.

Subagents may propose knowledge_updates[], but only the top-level orchestrator applies updates through this skill.

Inputs

The caller provides:

• ACCOUNT_ID
• AGENT: scope-audit, scope-controls, scope-exploit, or scope-investigate
• RUN_DIR or evidence file path when available
• Final disposition or outcome
• Evidence-backed candidate updates

Files To Update

Create Markdown files from the templates in knowledge/ when missing.

• knowledge/environment.md: operator-supplied stable environment facts only
• knowledge/observations.md: durable lessons, baselines, false positives, known-good patterns, automation notes, deployed-control notes, and org-wide patterns
• knowledge/coverage-gaps.md: telemetry gaps and AWS audit, enumeration, or authorization gaps
• knowledge/exploit-reasoning-notes.md: operator-reviewed expert reasoning note improvements for exploit analysis
• knowledge/hunt-reasoning-notes.md: operator-reviewed expert reasoning note improvements for investigations and hunts

There are no persistent investigation or research records under durable knowledge. Keep run-specific investigation and research artifacts under the run directory only.

Update Status Values

Every durable update must use one of:

• confirmed
• likely_normal
• suspicious
• false_positive
• coverage_gap
• needs_review

Safety Rules

• Do not write secrets, access keys, session tokens, passwords, raw credential material, or private keys.
• Do not write ARNs, account IDs, bucket names, role names, key IDs, or access key IDs. Resource identifiers are session-scoped.
• Do not write unsupported claims.
• Do not write run-specific noise unless it will help future investigations.
• Do not promote a pattern to org-wide unless at least two distinct account sections support it.
• Do not overwrite existing knowledge. Append or merge.
• Dedupe before appending.
• Every update must cite evidence: run directory, report path, query ID, event ID, finding ID, or analyst-approved note.
• Generalize resource-specific evidence before persistence. Use service names, control categories, event patterns, and behavior classes instead of exact identifiers.
• Before writing, scan candidate entries for exact identifier patterns: arn:aws:, 12-digit account IDs, access key IDs, key IDs, role names, user names, bucket names, and secret names. Redact or generalize the value. If the value cannot be generalized without losing meaning, skip it and report the skip reason.
• Evidence citations may point to run directories, reports, query IDs, event IDs, or finding IDs. Do not copy raw resource identifiers into the durable knowledge entry.
• Use dates in YYYY-MM-DD format.

Routing Rules

Route updates by type:

• Operator-supplied stable environment facts -> knowledge/environment.md
• Durable lessons, baselines, false positives, known-good patterns, automation, deployed-control notes, and org-wide patterns -> knowledge/observations.md
• Telemetry gaps and AWS audit, enumeration, or authorization gaps -> knowledge/coverage-gaps.md
• Expert reasoning note improvements -> propose operator-reviewed edits to knowledge/exploit-reasoning-notes.md or knowledge/hunt-reasoning-notes.md
• Completed investigations and threat-intel research -> do not persist as knowledge records; keep artifacts in the run directory

Required Output

After applying updates, return:

KNOWLEDGE_UPDATE
  status: complete|skipped|error
  files_updated:
    - path
  entries_added: 0
  entries_merged: 0
  entries_skipped: 0
  skipped_reasons:
    - ...
  operator_review_needed:
    - ...

Use skipped when the operator did not approve persistence or no evidence-backed updates exist.