Skip to content

SKILL.md

Latest commit

 

History

History
124 lines (103 loc) · 4.48 KB

SKILL.md

File metadata and controls

124 lines (103 loc) · 4.48 KB
name documentation-standards
description Clear technical documentation — JSDoc, Mermaid, READMEs, ADRs, C4 diagrams, ISMS policy citations
license MIT

Documentation Standards Skill

Context

Applies when writing READMEs, documenting APIs/functions/classes, creating architecture docs, adding JSDoc, drawing diagrams, writing ADRs, documenting security policies, or writing user guides.

Aligned with the architecture-documentation expectations in Secure Development Policy §Architecture Documentation Matrix.

Rules

  1. ISMS References — security-relevant docs cite the applicable Hack23 policy
  2. JSDoc for Public APIs — every export gets @param, @returns, @example (and @throws where relevant)
  3. Include TypeScript types in JSDoc context (types live in code; JSDoc describes behavior)
  4. Working examples — every snippet compiles and matches current behavior
  5. Document exceptions — @throws for every thrown error type
  6. Mermaid diagrams — never screenshots; always include source
  7. Keep READMEs current — updates ship in the same PR as code changes
  8. Link authoritative external docs — React, Three.js, vitest, ISO/NIST/CIS
  9. Show anti-patterns — ❌ examples beside ✅ for high-impact APIs
  10. Accessible markdown — semantic headings, descriptive links, alt text for images
  11. Heading hierarchy — H1 → H2 → H3, never skip levels
  12. Specify code-block languages ( ```typescript, ```bash, ```mermaid)
  13. ADRs for lasting decisions — numbered, dated, status tracked (Proposed / Accepted / Deprecated / Superseded)
  14. No PII in examples — synthetic data only

Documentation Portfolio (Hack23 standard)

File When Purpose
README.md Always Overview, badges, quick start, classification
SECURITY.md Always Vulnerability reporting
SECURITY_HEADERS.md Web Runtime headers
docs/ISMS_POLICY_MAPPING.md Always Feature → policy
docs/ARCHITECTURE.md Non-trivial C4 Context / Container / Component
docs/DATA_MODEL.md Stateful Data structures
docs/FLOWCHART.md Processes Business flows
docs/STATEDIAGRAM.md Stateful features State transitions
docs/FUTURE_*.md Roadmap Future-state counterparts

Examples

✅ JSDoc for a game function

/**
 * Calculates the active target count for a given game level.
 *
 * ISMS: Secure Development Policy §Phase 2 — Secure Coding
 *
 * @param level - Current game level (≥ 1)
 * @returns Number of active targets (1–3) for the level
 * @throws {RangeError} When `level` is not a finite integer ≥ 1
 *
 * @example
 * ```typescript
 * getTargetCountForLevel(1); // 1
 * getTargetCountForLevel(5); // 2
 * getTargetCountForLevel(8); // 3
 * ```
 */
export function getTargetCountForLevel(level: number): number {
  if (!Number.isFinite(level) || level < 1) {
    throw new RangeError('level must be a finite integer ≥ 1');
  }
  if (level <= 3) return 1;
  if (level <= 6) return 2;
  return 3;
}

✅ C4 Context diagram (Mermaid)

```mermaid
graph TB
  Player((Player)) -->|Plays| App[Target Shooter SPA]
  App -->|Loads assets| CDN[(Bundled static assets)]
  App -->|Audio| Howler[Howler.js]
  App -->|Renders| Three[Three.js / WebGL]
```

✅ ADR skeleton

# ADR 0001 — Adopt Vitest for Unit Testing
- **Status:** Accepted (2025-11-10)
- **Context:** Need fast, ESM-native test runner compatible with Vite.
- **Decision:** Use Vitest with jsdom.
- **Consequences:** Faster feedback; minor migration from Jest APIs.
- **ISMS:** Secure Development Policy §Phase 3 — Security Testing

❌ Anti-Patterns

// BAD: exported function with no JSDoc
export function calc(x: number) { return x * 2; }

// BAD: @example that contradicts behavior
/** @example calc("2"); // 4 */
export function calc(v: number): number { return v * 2; }

// BAD: screenshot-only diagram
// (not maintainable, not accessible, not diffable)

Validation Checklist

  • Every public export has JSDoc with a working @example
  • Diagrams are Mermaid source (not images)
  • All internal + external links resolve
  • Heading hierarchy is correct (no skipped levels)
  • Code blocks specify a language
  • Security docs cite the applicable ISMS policy
  • Anti-patterns shown for non-trivial APIs
  • No PII or real-user data in examples