CtrlK
BlogDocsLog inGet started
Tessl Logo

documentation-standards

Scaffolds issue docs, ADRs, README outlines, changelog entries, roadmap updates, and Mermaid architecture diagrams using project templates. Use when drafting an ADR, writing a changelog, updating the roadmap after a feature ships, creating a README for a new library, or diagramming a system flow.

100

Quality

100%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

SKILL.md
Quality
Evals
Security

Documentation Standards

For project-specific directory structure and practices, see docs-structure.md.

Issue Documentation Template

### ISSUE-ID: Brief Description

**Issue ID:** ISSUE-ID
**Status:** Known Limitation | Fixed | Workaround Available
**Severity:** Critical | High | Medium | Low
**Impact:** [What user/developer experience is affected]

#### Problem
[Clear description of the issue]

#### Root Cause
[Technical explanation]

#### Solution Options
1. **Option A** — [Description] — Pros: ... Cons: ...
2. **Option B** — [Description]

#### Related Files
- `path/to/file.ts` — [What it does]

Roadmap Update Template

When a feature is completed: add COMPLETE row with date and owner, list files changed with rationale, add validation command + exit status, move to Completed section with one-line release note.

- Feature: Add priceRange filter
  Completed: 2026-03-30 | Owner: @developer
  Files: src/components/PriceRangeFilter.tsx, src/lib/filters.ts
  Validation: `pnpm build` (exit 0)

Architecture Decision Record Template

## ADR-NNN: Decision Title
**Date:** YYYY-MM-DD
**Status:** Accepted | Superseded | Deprecated
**Context:** [Why this decision was needed]
**Decision:** [What was decided]
**Consequences:** [Impact of the decision]
**Alternatives Considered:** [What else was evaluated]

README Template

# Feature / Library Name
One-sentence summary of what this does and why it exists.
## Quick Start
Brief usage example or setup steps.
## Architecture
High-level overview. Include a Mermaid diagram for non-trivial systems.
## Key Files
| File | Purpose |
|------|---------|
| `src/handler.ts` | Request handling logic |
| `src/schema.ts` | Validation schemas |

Mermaid Diagrams

Keep diagrams focused — one concern per diagram, max 10–12 nodes.

flowchart TD
  A[Receive Request] --> B{Authenticated?}
  B -- Yes --> C[Process]
  B -- No --> D[Return 401]
  • flowchart TD for pipelines, LR for request flows, sequenceDiagram for API flows, erDiagram for data models
  • Add %% Title: ... on complex diagrams; use verb labels on arrows

Changelog Entry Template

Group entries by Conventional Commits type under a version heading:

## [1.2.0] — YYYY-MM-DD
### Added
- feat: Add retry logic to API client (#123)
### Fixed
- fix: Resolve race condition in queue processor (#127)
### Changed
- refactor: Extract validation into shared module (#125)
  • One line per change; reference the PR or issue number
  • Imperative mood; most recent version first

Documentation workflow

  1. Draft — create doc using templates above.
  2. Validate — run checks: 
    npx markdown-link-check docs/**/*.md && pnpm prettier --check "docs/**/*.md"
    • Fail → fix broken paths/formatting → re-run step 2.
  3. Review — peer review via PR; address comments.
  4. Publish — merge; update roadmap/changelog.
  5. Pre-Merge Checklist — accuracy ✓, links resolve ✓, front matter valid ✓, no TODO placeholders ✓, formatting consistent ✓.

Writing, Formatting & Anti-Patterns

See WRITING-GUIDE.md for writing guidelines, formatting rules, and anti-patterns.

Repository
monkilabs/opencastle
Commit

f5c8508

Last updated
Created

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

Claim skill