Pre-Flight Check Skill

Before writing code, run through these checklists to validate your approach and catch potential issues early.

⚠️ MANDATORY: Git Workflow Check (DO THIS FIRST)

STOP! Before ANY code changes, complete this checklist:

1. Issue Check

# What issue are you working on?
bd show <issue-id>

# If no issue exists, create one first:
bd create --title="..." --type=feature|bug|task --priority=2

• • Issue exists and is claimed (bd update <id> --status=in_progress)

2. Branch Check

# What branch are you on?
git branch --show-current

# Are you on main? CREATE A FEATURE BRANCH:
git checkout -b feature/<issue-id>-short-description

• • On a feature branch (NOT main)
• • Branch follows naming: <type>/<issue-id>-description

3. Worklog Check

# Does a worklog entry exist for this issue?
ls .worklog/*<issue-id>*

• • Worklog entry exists or will be created before completing work

Red Flags - STOP if any are true:

Only proceed to code changes after ALL boxes are checked.

When to Use This Skill

Activate pre-flight checks when:

• •Starting work on any issue (git workflow check FIRST)
• •Creating a new file
• •Making significant edits to existing code
• •Implementing a new feature
• •Uncertain about the right approach

Quick Decision Tree

What are you creating?
│
├─ HTML page/component
│  └─ Use: HTML Pre-Flight Checklist
│     └─ Check: xhtml-author, accessibility-checker, metadata skills
│
├─ CSS file
│  └─ Use: CSS Pre-Flight Checklist
│     └─ Check: css-author, design-tokens skills
│
├─ JavaScript file
│  └─ Use: JavaScript Pre-Flight Checklist
│     └─ Check: javascript-author skill
│
├─ Form
│  └─ Use: Forms Pre-Flight Checklist
│     └─ Check: forms skill
│
├─ Image addition
│  └─ Use: Images Pre-Flight Checklist
│     └─ Check: responsive-images skill
│
└─ New site/project
   └─ Use: Site Essentials Pre-Flight Checklist
      └─ Check: site-scaffold skill

Auto-Invoke Rules

These skills should be invoked automatically based on context:

Common Multi-Skill Patterns

When building these features, invoke ALL listed skills:

Critical: Icons

ALWAYS invoke the icons skill when adding visual indicators. Theme toggles, buttons with icons, navigation icons, status indicators - ALL should use <icon-wc>, never inline SVGs.

See COMPOSITIONS.md for more multi-skill patterns.

HTML Pre-Flight Checklist

Before writing HTML, verify:

Structure

• • What page type is this? (homepage, article, product, contact, etc.)
• • What semantic landmark elements are needed? (<header>, <nav>, <main>, <aside>, <footer>)
• • Is there existing content to preserve or migrate?
• • What heading hierarchy makes sense? (single <h1>, logical <h2>-<h6>)

Patterns to Consider

• • Does this match an existing pattern in .claude/patterns/pages/?
• • Are there custom elements in .claude/schemas/elements.json that apply?
• • Should this use a documented page pattern from the patterns skill?

Metadata

• • What metadata profile applies? (default, article, product, etc.)
• • Is Open Graph data needed for social sharing?
• • What canonical URL should be used?

Accessibility

• • Will all interactive elements be keyboard accessible?
• • Are proper ARIA labels planned for navigation regions?
• • Will images have meaningful alt text?

Potential Issues

CSS Pre-Flight Checklist

Before writing CSS, verify:

Architecture

• • Which layer does this belong to? (base, components, utilities, overrides)
• • Does a token already exist for this value in _tokens.css?
• • Is this component-scoped, section-scoped, or page-scoped?

Patterns to Consider

• • Can this use existing custom properties?
• • Should this use native nesting (max depth 3)?
• • Would :has() enable CSS-only interactivity?
• • Are there existing patterns in .claude/patterns/ or .claude/styles/?

Selectors

• • Using element or attribute selectors? (preferred over classes)
• • Using data-* attributes for state? (not classes)
• • Avoiding overly specific selectors?

Potential Issues

JavaScript Pre-Flight Checklist

Before writing JavaScript, verify:

TDD Check (Test-First)

• • Is this a new file or significant new functionality?
• • Does a corresponding test file exist?
• • If not, will you create the test FIRST? (Red-Green-Refactor)

To check TDD mode: /tdd status To change mode: /tdd strict or /tdd advisory

Architecture

• • Is JavaScript actually needed? (CSS-only alternatives?)
• • Is this a Web Component? (needs Shadow DOM, lifecycle methods)
• • What's the functional core? (pure getters, computed values)
• • What's the imperative shell? (DOM updates, event handlers)

File Structure

• • Does this need separate template/styles/i18n files?
• • Where should this file live? (src/components/, src/scripts/)
• • What should be exported? (named exports only)

Patterns to Consider

• • Language fallback chain pattern for i18n?
• • CustomEvent for component communication?
• • MutationObserver for lang changes?
• • Cleanup in disconnectedCallback?

Potential Issues

Forms Pre-Flight Checklist

Before building forms, verify:

Structure

• • Using <form-field> custom element pattern?
• • Is there a submit action and method defined?
• • What validation is needed? (HTML5 attributes vs custom)

Accessibility

• • Every input has a <label> with matching for/id?
• • Error messages have <output> containers?
• • Required fields marked with required attribute?
• • Field descriptions linked via aria-describedby?

Patterns to Consider

• • <output> for real-time validation feedback?
• • autocomplete attributes for user convenience?
• • inputmode for mobile keyboards?

Potential Issues

Images Pre-Flight Checklist

Before adding images, verify:

Files

• • Do WebP and AVIF alternatives exist?
• • Is the file under 200KB?
• • Are multiple sizes available for srcset?

HTML Attributes

• • alt attribute with meaningful description?
• • loading="lazy" for below-fold images?
• • decoding="async" for non-critical images?
• • width and height for layout stability?

Patterns to Consider

• • Should this use <picture> for art direction?
• • What sizes attribute values are needed?
• • Should this be a <figure> with <figcaption>?

Potential Issues

Site Essentials Pre-Flight Checklist

Before launching or when setting up a new site, verify these essentials exist:

Core Files

• • robots.txt - Search engine directives
• • sitemap.xml - XML sitemap for crawlers
• • humans.txt - Team credits and site info
• • manifest.json - PWA web app manifest

Error & Fallback Pages

• • 404.html - Not found error page
• • 500.html - Server error page (static, minimal dependencies)
• • offline.html - Service worker offline fallback
• • noscript.html - JavaScript-disabled fallback (if app requires JS)

Security

• • .well-known/security.txt - Security contact info (RFC 9116)

Favicon Set

• • favicon.svg - Vector favicon (modern browsers)
• • favicon.ico - Legacy favicon (32x32)
• • apple-touch-icon.png - iOS home screen (180x180)
• • icon-192.png - PWA icon small
• • icon-512.png - PWA icon large
• • og-image.png - Social sharing (1200x630)

Quick Check Command

# Check for essential files in site root
ls -la robots.txt sitemap.xml humans.txt manifest.json 404.html 500.html 2>/dev/null
ls -la .well-known/security.txt 2>/dev/null

When to Create These

See site-scaffold skill for templates.

Pattern Matching Guide

When the user says... suggest this pattern:

Red Flags to Watch For

Stop and reconsider if you notice:

1. •"Just add a div" - There's almost always a semantic element
2. •"Add a class for state" - Use data-* attributes instead
3. •"Quick inline style" - Will fail validation
4. •"Just copy this code" - Check if a pattern/skill exists first
5. •"Add JavaScript for..." - Check if CSS can do it first
6. •"Skip the alt text" - Never acceptable
7. •"We'll fix it later" - Validation catches issues now

Verification Commands

After writing, verify with:

# HTML validation
npm run lint

# CSS validation
npm run lint:css

# JavaScript validation
npm run lint:js

# Accessibility check
npm run a11y

# Full validation
npm run lint:all

⚠️ MANDATORY: Completion Checklist (DO THIS LAST)

Before saying "done", complete this checklist:

1. Tests Pass

npm test
npm run lint:all
npm run test:coverage  # Check for missing tests

• • All tests pass
• • All linters pass
• • New scripts have corresponding test files

2. Worklog Updated

• • Worklog entry in .worklog/ documents changes made
• • Files modified are listed
• • Any decisions/issues are noted

3. Commit Changes

git add <files>
git commit -m "type(scope): description"

• • Changes committed with conventional commit format
• • Commit message references issue if applicable

4. Request UAT

/uat request <feature-name>
# This adds uat:requested label to the issue

• • UAT requested via /uat request <feature-name>
• • Issue has uat:requested label
• • Testing instructions provided for human in .worklog/uat-<feature>.md

5. Wait for Approval

# Check UAT status
/uat status <feature-name>
# Or check issue labels
bd show <issue-id>

• • DO NOT close issue until uat:approved label is present
• • If denied (uat:denied label), address feedback and re-request UAT
• • Only close when approved: bd close <issue-id>

Completion Red Flags:

Related Skills

• •git-workflow - Enforce structured git workflow with conventional commits
• •tdd - Test-Driven Development workflow for JS/TS files
• •unit-testing - Write unit tests for JavaScript files
• •xhtml-author - Write valid XHTML-strict HTML5 markup
• •css-author - Modern CSS organization with @layer
• •javascript-author - Vanilla JavaScript for Web Components
• •icons - Lucide icon library with <icon-wc> Web Component
• •forms - HTML-first form patterns with CSS-only validation
• •accessibility-checker - Ensure WCAG2AA accessibility compliance