Manage Risk Knowledge

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

Repository Structure

code

├── 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

code

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"):

•
Validate uniqueness
- •Check domains/ for existing folder
- •Check indexes/knowledge-map.yml for duplicate domain_name or keywords
•
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?)
•
Create files using templates from references/templates.md
- •domains/{name}/spec.md
- •domains/{name}/risks.md

•

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

yaml

- domain_name: "表示名 (English)"
  description: "..."
  keywords: [...]
  related_files:
    common_risks: [...]
    domain_knowledge:
      - "domains/{name}/spec.md"
      - "domains/{name}/risks.md"

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

Add Incident Workflow

When user reports a past incident:

•
Collect information
- •Date, duration, severity
- •What happened (user-facing impact)
- •Root cause (technical)
- •Affected domain(s)
•
Create incident file
- •Filename: incidents/YYYY-short-description.md
- •Use template from references/templates.md
•
Update related risks
- •Add Related Incident link to relevant domains/{name}/risks.md
- •If new risk pattern, add new risk entry
•
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:

•
Locate target file
- •Domain-specific: domains/{name}/risks.md
- •Cross-cutting: common-risks/{category}.md
•
Check for duplicates
- •Search existing risks for similar patterns
- •Warn if overlap detected
•
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
•
Update knowledge-map.yml keywords if new terms should trigger this domain

Update Common Risk Workflow

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

•
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
•
Add/update risk following existing format
•
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:

bash

# 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:

bash

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:

bash

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:

bash

python scripts/add_domain.py [repo_path]

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

Note: Scripts require PyYAML. Install with:

bash

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