documentation-standards

name	documentation-standards
description	Enforces consistent documentation standards for Black Trigram — JSDoc/TSDoc completeness, architecture currency, bilingual Korean-English content, and security documentation updates
license	MIT

📝 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

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

/**
 * 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

/**
 * 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

/**
 * 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