# Documentation Standards

> Enforces consistent documentation standards for Black Trigram — JSDoc/TSDoc completeness, architecture currency, bilingual Korean-English content, and security documentation updates Use when this capability is needed.

- Skill: `tomevault-io/documentation-standards-9` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/documentation-standards-9`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/documentation-standards-9/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/documentation-standards-9

---


# 📝 Documentation Standards Skill

> **Strategic Principle**: Great documentation is as important as great code. Document for clarity, maintainability, and knowledge transfer.

## 🎯 Purpose

Enforce consistent documentation standards across Black Trigram, ensuring code, APIs, architecture, and user guides are well-documented with bilingual Korean-English support.

**Reference**: [Hack23 ISMS Secure Development Policy](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)

## Enforcement Rules

### Rule 1: JSDoc/TSDoc for Public APIs
```
IF (exported function, class, interface, or type)
THEN (add JSDoc with @param, @returns, @throws, @example)
ELSE (reject - undocumented public APIs impede maintainability)
```

### Rule 2: Architecture Documentation
```
IF (modifying component structure OR data models OR system design)
THEN (update relevant C4 architecture documents: ARCHITECTURE.md, DATA_MODEL.md, etc.)
ELSE (documentation drift - refer to c4-architecture-documentation skill)
```

### Rule 3: Bilingual Documentation
```
IF (user-facing text OR Korean martial arts terminology)
THEN (provide both Korean and English with romanization where applicable)
ELSE (incomplete documentation for international audience)
```

### Rule 4: Security Documentation
```
IF (security-related change OR authentication/authorization)
THEN (update SECURITY_ARCHITECTURE.md AND add ISMS policy references)
ELSE (security documentation gap - refer to security-architecture-validation skill)
```

## Core Patterns

### JSDoc Format
```typescript
/**
 * Calculates damage multiplier based on trigram stance alignment.
 *
 * Uses the Eight Trigram (팔괘) opposition system to determine
 * effectiveness of attacks between different stances.
 *
 * @param attackerStance - The attacker's current trigram stance
 * @param defenderStance - The defender's current trigram stance
 * @returns Damage multiplier between 0.5 (disadvantage) and 2.0 (advantage)
 *
 * @example
 * ```typescript
 * const multiplier = calculateStanceMultiplier('geon', 'gon');
 * // Returns: 1.5 (Heaven vs Earth advantage)
 * ```
 *
 * @see {@link TrigramStance} for valid stance values
 */
export function calculateStanceMultiplier(
  attackerStance: TrigramStance,
  defenderStance: TrigramStance,
): number { /* ... */ }
```

### Interface Documentation
```typescript
/**
 * Represents a vital point (급소) target in the combat system.
 *
 * @property names - Bilingual names (Korean, English, romanized)
 * @property position - 2D coordinates on the character model
 * @property category - Anatomical category (neurological, cardiovascular, etc.)
 * @property severity - Impact severity level
 */
export interface VitalPoint {
  readonly id: string;
  readonly names: BilingualText;
  readonly position: Position;
  readonly category: VitalPointCategory;
  readonly severity: VitalPointSeverity;
}
```

### Component Documentation
```typescript
/**
 * CombatHUD displays the heads-up display during combat.
 *
 * Renders player health, ki energy, stance indicator, and
 * combat log using Html overlays over the Three.js scene.
 *
 * @remarks
 * Uses KOREAN_COLORS for consistent cyberpunk Korean aesthetic.
 * All text is bilingual (Korean | English).
 *
 * @example
 * ```tsx
 * <CombatHUD
 *   player={playerState}
 *   width={1200}
 *   height={800}
 *   isMobile={false}
 * />
 * ```
 */
```

## Required Architecture Documents

| Document | Purpose | Update When |
|----------|---------|-------------|
| `ARCHITECTURE.md` | C4 models (Context, Container, Component) | Structure changes |
| `DATA_MODEL.md` | Data structures and relationships | Type changes |
| `FLOWCHART.md` | Business process and data flows | Flow changes |
| `STATEDIAGRAM.md` | System state transitions | State changes |
| `MINDMAP.md` | Conceptual relationships | Concept changes |
| `SWOT.md` | Strategic analysis | Strategy changes |
| `SECURITY_ARCHITECTURE.md` | Security design and controls | Security changes |
| `FUTURE_*.md` | Planned improvements and roadmap | Planning changes |

## Testing Requirements

- ✅ TypeDoc generates without errors (`npm run docs`)
- ✅ All public APIs have JSDoc comments
- ✅ Architecture documents are consistent with code
- ✅ Korean terminology includes romanization
- ✅ README.md is current and accurate

## Compliance

- **ISO 27001:2022**: A.5.37 (Documented operating procedures)
- **NIST CSF 2.0**: GV.PO (Policy), ID.AM (Asset Management)
- **Hack23 ISMS**: Information Security Policy, Secure Development Policy

---

**흑괘의 문서화** - _Documentation of the Black Trigram_

---
> Source: [Hack23/blacktrigram](https://github.com/Hack23/blacktrigram) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-16 -->