Waymark Maintenance

This skill guides systematic waymark placement and maintenance across a codebase. It delegates to the waymarker agent for execution. The agent loads the waymarks skill for grammar reference and search commands.

Quick Start

Check current TLDR coverage:

!.agents/skills/waymark-maintenance/scripts/coverage-report --stats

Priority: TLDR Coverage

TLDRs are the foundation of waymark coverage. Every source file should have a TLDR describing what it does. Without TLDRs, codebase navigation is impaired for both humans and agents.

Coverage Workflow

1. Audit: Run coverage-report --missing-tldr to find gaps
2. Prioritize: Start with entry points, core modules, then utilities
3. Write: Add TLDRs following the patterns below
4. Verify: Re-run coverage to confirm improvement

Writing TLDRs

The Rules

• One per file: Exactly one tldr ::: per file
• First waymark: Place after shebang/frontmatter, before code
• 8-14 words: Concise, active voice, capability-first
• No filler: Avoid "This file contains...", "Module for...", "Utilities..."

Placement by File Type

TypeScript/JavaScript:

// tldr ::: handles user authentication and JWT token lifecycle

import { sign, verify } from 'jsonwebtoken';

Python:

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

# tldr ::: manages database migrations and schema versioning

import sqlite3

Markdown:

---
title: API Guide
---

<!-- tldr ::: REST API reference with authentication examples #docs -->

# API Guide

Shell:

#!/bin/bash

# tldr ::: deployment script for production Kubernetes cluster

set -euo pipefail

Sentence Patterns

Write one sentence describing what the file delivers:

Strong Verbs

Use active, specific verbs:

• validates, processes, transforms, parses
• renders, displays, presents
• manages, orchestrates, coordinates
• fetches, retrieves, queries
• generates, creates, builds
• handles, routes, dispatches

Starred TLDRs

Use *tldr for critical files that must be read first:

// *tldr ::: main application entry wiring Express middleware
// *tldr ::: core authentication service all routes depend on

Reserve for: entry points, core infrastructure, security-critical modules.

Documentation TLDRs

Documentation files must include #docs tag:

<!-- tldr ::: API authentication guide using JWT tokens #docs/guide -->
<!-- tldr ::: database schema migration reference #docs/reference -->

Writing About Waymarks

about ::: markers describe the code section immediately following them.

Placement

Place directly above the construct (6-12 words):

// about ::: validates JWT tokens and extracts claims
export function validateToken(token: string): Claims {

Patterns by Construct

Scope Rule

Focus on the section, not the file. Don't restate the TLDR:

// tldr ::: user authentication service

// about ::: validates password against security policy  // ✓ Section-specific
function validatePassword(password: string) {}

// about ::: handles user authentication  // ✗ Too broad, same as tldr
function validatePassword(password: string) {}

Maintaining Waymarks

Stale Waymark Detection

Waymarks become stale when code changes but waymarks don't. Look for:

• Completed todos: todo ::: for work that's done
• Fixed bugs: fix ::: for bugs that are resolved
• Inaccurate descriptions: TLDRs/abouts that don't match current behavior
• Orphaned references: see:#token pointing to removed code

Update Process

1. Read the code to understand current behavior
2. Compare against existing waymark content
3. Update waymark to match reality, or delete if no longer relevant
4. Never leave inaccurate waymarks—they're worse than none

Pre-Merge Audit

Before merging, check for items that should be cleared:

find-waymarks -F              # Flagged items (must clear before merge)
find-waymarks -S              # Starred items (should address)
find-waymarks -t wip          # WIP markers

See the waymarks skill for full search options.

Files to Skip

Don't add waymarks to:

• Generated files: .d.ts, .generated.*, @generated headers
• Index/barrel files: TLDR optional if only re-exports
• Test fixtures: Skip unless complex logic exists
• Lock files: package-lock.json, bun.lockb, etc.
• Build artifacts: dist/, build/, .next/
• Empty files: Flag for removal rather than adding waymarks

Files That Need TLDRs

Prioritize in this order:

1. Entry points: index.ts, main.ts, app.ts
2. Core services: Authentication, database, API handlers
3. Utilities: Shared helpers, formatters, validators
4. Configuration: Non-trivial config files
5. Documentation: All markdown files (with #docs tag)
6. Tests: Test files with complex setup

Common Mistakes

Too Vague

// Bad:  // tldr ::: utilities
// Good: // tldr ::: date parsing utilities with timezone normalization

Too Long

// Bad:  // tldr ::: this file contains the main authentication service that handles user login, registration, password reset, and session management using JWT tokens
// Good: // tldr ::: authentication service with login, registration, and JWT sessions

Wrong Placement

// Bad:
import { hash } from 'bcrypt';
// tldr ::: authentication service  // Too late!

// Good:
// tldr ::: authentication service with bcrypt password hashing
import { hash } from 'bcrypt';

Missing Required Tag

<!-- Bad:  tldr ::: API documentation for user endpoints -->
<!-- Good: tldr ::: API documentation for user endpoints #docs/api -->

Coverage Script

coverage-report              # Files missing TLDRs
coverage-report --stats      # Coverage percentage
coverage-report --all        # All files with status
coverage-report --json       # JSON output for tooling
coverage-report --help       # All options

Script location: .agents/skills/waymark-maintenance/scripts/coverage-report

Delegation

This skill delegates to the waymarker agent which operates in two modes:

• Conservative (default): Reports findings, suggests waymarks, doesn't modify files
• Autonomous: Adds waymarks directly when instructed with "go ahead", "add them", etc.

Always start with conservative mode to review suggestions before bulk changes.