Manage Risk Knowledge

Unified skill for maintaining the risk knowledge base. Handles domain creation, incident recording, risk updates, and index synchronization.

Repository Structure

├── indexes/knowledge-map.yml    # Keyword → file routing (MUST update)
├── common-risks/                # Cross-cutting risks (security, performance, availability)
├── domains/{name}/              # Domain-specific knowledge
│   ├── spec.md                  # Feature specification
│   └── risks.md                 # Domain-specific risks
└── incidents/                   # Past incident records

Workflow Decision Tree

User Request
    │
    ├─ "Add new domain/feature" ──────► Add Domain Workflow
    │
    ├─ "Record incident" ─────────────► Add Incident Workflow
    │
    ├─ "Add/update risk" ─────────────► Update Risk Workflow
    │
    └─ "Update common risk" ──────────► Update Common Risk Workflow

Add Domain Workflow

When user wants to add a new feature/domain (e.g., "notification", "search"):

1. Validate uniqueness

- Check domains/ for existing folder - Check indexes/knowledge-map.yml for duplicate domain_name or keywords

1. Collect information (ask if not provided)

- Domain name (kebab-case for folder, display name for YAML) - Keywords (3-5 terms that should trigger this domain) - Brief description - Related common risks (security? performance? availability?)

1. Create files using templates from references/templates.md

- domains/{name}/spec.md - domains/{name}/risks.md

1. Update index - Add entry to indexes/knowledge-map.yml:

``yaml - domainname: "表示名 (English)" description: "..." keywords: [...] relatedfiles: commonrisks: [...] domainknowledge: - "domains/{name}/spec.md" - "domains/{name}/risks.md" ``

1. Verify - Confirm all paths in knowledge-map.yml exist

Add Incident Workflow

When user reports a past incident:

1. Collect information

- Date, duration, severity - What happened (user-facing impact) - Root cause (technical) - Affected domain(s)

1. Create incident file

- Filename: incidents/YYYY-short-description.md - Use template from references/templates.md

1. Update related risks

- Add Related Incident link to relevant domains/{name}/risks.md - If new risk pattern, add new risk entry

1. Bidirectional linking

- Incident → risks.md (in "Related Risks" section) - risks.md → incident (in risk entry)

Update Risk Workflow

When adding or modifying a risk in existing domain:

1. Locate target file

- Domain-specific: domains/{name}/risks.md - Cross-cutting: common-risks/{category}.md

1. Check for duplicates

- Search existing risks for similar patterns - Warn if overlap detected

1. Add/update risk entry with required fields:

- Details: What can go wrong - Countermeasures: How to prevent/mitigate - Severity: Critical/High/Medium/Low - Related Incident: Link if applicable

1. Update knowledge-map.yml keywords if new terms should trigger this domain

Update Common Risk Workflow

For cross-cutting risks (security, performance, availability):

1. Identify category from common-risks/:

- security.md - Injection, auth bypass, data exposure - performance.md - N+1, memory, connection exhaustion - availability.md - Service outage, login failure

1. Add/update risk following existing format

1. Check domain linkage - Ensure relevant domains reference this common risk in knowledge-map.yml

Validation

Before completing any operation, run validation checks:

Automated Validation Scripts

Use provided scripts for comprehensive validation:

# Full validation (recommended)
python scripts/validate_knowledge.py

# Check bidirectional links only
python scripts/check_links.py

When to validate:

• After adding new domain
• After recording incident
• After updating risks
• Before committing changes

Validation checks:

• Block: Duplicate domain/keyword, broken file paths, missing required fields
• Warn: Similar keywords, duplicate risk patterns, missing incident links

See references/validation-rules.md for detailed rules.

Scripts

Three utility scripts are provided in scripts/ directory:

validate_knowledge.py

Comprehensive validation of entire knowledge base.

Checks:

• YAML syntax in knowledge-map.yml
• File path existence
• Required fields in all documents
• Duplicate domains and keywords
• Bidirectional link consistency

Usage:

python scripts/validate_knowledge.py [repo_path]

When to use: After any modification to verify integrity.

check_links.py

Focused link validation between incidents and risks.

Checks:

• Incident → Risk references
• Risk → Incident references
• Knowledge-map.yml file references
• Broken file links

Usage:

python scripts/check_links.py [repo_path]

When to use: When adding/updating cross-references.

add_domain.py

Interactive domain creation wizard.

Features:

• Validates domain uniqueness
• Creates spec.md and risks.md from templates
• Updates knowledge-map.yml automatically
• Guides keyword and common risk selection

Usage:

python scripts/add_domain.py [repo_path]

When to use: When adding new domain (alternative to manual workflow).

Note: Scripts require PyYAML. Install with:

pip install -r scripts/requirements.txt

References

• references/templates.md - File templates for spec.md, risks.md, incidents/
• references/validation-rules.md - Validation rules and checks