Skip to content

README

Jump to bottom
miswired edited this page Feb 7, 2026 · 2 revisions

Documentation Verification Index

This directory tracks verification of technical claims in Glitchy documentation against authoritative sources. Each documentation file has a corresponding verification file that records sources, confidence levels, and verification status for all technical claims.

Purpose

The verification system ensures:

  • Accuracy: All technical claims are validated against authoritative sources
  • Traceability: Sources are documented for future reference
  • Quality: Documentation maintains high standards of technical correctness
  • Maintainability: Future changes can be verified against established sources

Verification Status

Document Status Verified Claims Issues Found Last Updated
Tutorial-Getting-Started ✅ Complete 35/35 0 2026-02-01
Tutorial-First-Glitch ✅ Complete 40/40 0 2026-02-01
HowTo-Setup-PlatformIO ✅ Complete 32/32 3 2026-02-02
HowTo-Flash-Firmware ✅ Complete 25/25 3 2026-02-02
HowTo-Configure-WiFi ✅ Complete 22/22 3 2026-02-02
HowTo-Update-WebGUI ✅ Complete 28/28 4 2026-02-02
HowTo-Setup-KiCad ✅ Complete 26/26 2 2026-02-02
HowTo-Troubleshoot ✅ Complete 45/45 5 2026-02-02

Overall Progress: 8/8 documents verified (100% complete)

How to Use This System

For Reviewers

  1. Check overall progress: Review the status table above
  2. Review specific document: Click through to individual verification files
  3. See task tracking: Check ../glitchy/openspec/changes/rewrite-documentation-diataxis/tasks.md for high-level task status

For Contributors

When creating or modifying documentation:

  1. Create verification file: Copy TEMPLATE.md and rename to VERIFICATION-{document-name}.md
  2. Extract claims: Identify all technical claims in the source document
  3. Research sources: Find authoritative sources for each claim
  4. Record findings: Document sources, confidence levels, and verification status
  5. Update index: Update the status table in this README
  6. Update OpenSpec: Mark corresponding task complete in OpenSpec tasks.md

Verification File Format

Each verification file follows this structure:

# Verification: {Document-Name}.md
**Status**: {Not Started|In Progress|Complete|Needs Review}
**Verified**: {X}/{Y} claims
**Last Updated**: YYYY-MM-DD

## Summary
Brief overview of document and verification scope.

## {Category Name} Claims

### Claim: {Exact claim text}
- **Source**: {Specific reference with file path, line number, or page number}
- **Confidence**: {HIGH|MEDIUM|LOW|UNKNOWN}
- **Status**: {✓ Verified | ❌ Incorrect | ⚠️ Needs Testing | ? Unknown}
- **Notes**: {Additional context, test procedures, or corrections needed}

Confidence Levels

HIGH

Claim verified against:

  • Official manufacturer documentation (datasheets, technical reference manuals)
  • Project source code with specific line references
  • Physical hardware testing with documented results
  • KiCad schematics and PCB designs

Example: "ESP32-S3 has 45 GPIO pins" verified against ESP32-S3 Technical Reference Manual

MEDIUM

Claim supported by:

  • Logical inference from HIGH confidence sources
  • Academic papers or peer-reviewed research
  • Technical books by recognized experts
  • Secondary component datasheets

Example: "Glitch timing resolution is approximately 18ns" inferred from SPI bus speed specifications

LOW

Claim based on:

  • Assumptions or project naming conventions
  • Anecdotal evidence or informal testing
  • Blog posts or forum discussions
  • Incomplete or indirect sources

Example: "Default WiFi SSID is 'Glitchy'" assumed from project name, not found in code

UNKNOWN

No source found for claim:

  • Requires investigation or research
  • Needs expert review
  • Requires hardware testing
  • May need correction or removal

Example: "Glitch success rate is 85%" - no source or methodology documented

Status Icons

  • ✓ Verified: Claim confirmed against authoritative source
  • ❌ Incorrect: Claim contradicts authoritative source, needs correction
  • ⚠️ Needs Testing: Claim requires hardware testing or validation
  • ? Unknown: No source found, requires investigation

Authoritative Source Guidelines

PRIMARY Sources (Preferred)

Official Documentation:

  • Espressif ESP32-S3 Technical Reference Manual
  • ESP32-S3 Datasheet
  • Component datasheets (FETs, op-amps, ADCs)
  • Manufacturer application notes

Project Artifacts:

  • Source code: Code/Glitchy/src/, Code/Glitchy/include/
  • KiCad schematics and PCB designs
  • Configuration files
  • Hardware testing results

SECONDARY Sources (When Primary Unavailable)

Academic & Research:

  • Peer-reviewed papers (CHES, IEEE S&P, USENIX Security conferences)
  • Technical books: "Power Analysis Attacks" (Mangard et al.), "The Hardware Hacker" (Huang)
  • Published research on fault injection and side-channel attacks

Framework Documentation:

  • PlatformIO documentation
  • Arduino framework documentation
  • Library documentation for dependencies

INVALID Sources (Do Not Use)

  • Blog posts (unless from official manufacturer)
  • Forum discussions or Reddit threads
  • Unverified tutorials or guides
  • AI-generated content without verification
  • Assumptions or guesses

Hardware Testing Requirements

Some claims can only be verified through testing on physical Glitchy hardware:

Requires Hardware Testing:

  • WiFi SSID and default network configuration
  • Default IP addresses
  • Web interface behavior and responses
  • Actual glitch timing measurements
  • Power consumption values
  • Pin voltage levels

Testing Procedure:

  1. Document test setup and conditions
  2. Record step-by-step test procedure
  3. Capture results (screenshots, measurements, logs)
  4. Note any deviations or unexpected behavior
  5. Update verification file with "✓ Verified" + "TESTED" confidence

Verification Checklist

Before marking a verification file as complete:

  • All technical claims identified and extracted from source document
  • Claims organized by category (Hardware, Software, Configuration, etc.)
  • Each claim has source citation with specific references
  • Each claim has confidence level (HIGH/MEDIUM/LOW/UNKNOWN)
  • Each claim has status icon (✓ ❌ ⚠️ ?)
  • Hardware-dependent claims marked "⚠️ Needs Testing" if not yet tested
  • Incorrect claims documented with proposed corrections
  • Summary section completed with overview and statistics
  • Status header updated (status, claim count, date)
  • Index table in this README updated
  • Corresponding OpenSpec task marked complete

Integration with OpenSpec

This verification system integrates with OpenSpec for high-level task tracking:

  • OpenSpec spec: See ../glitchy/openspec/specs/documentation-verification/spec.md for detailed requirements
  • OpenSpec tasks: See ../glitchy/openspec/changes/rewrite-documentation-diataxis/tasks.md for task tracking
  • Relationship: OpenSpec tracks WHAT needs verification (document-level), these files track HOW claims were verified (claim-level)

Agent Instructions

AI agents working on Glitchy documentation should:

  1. Before creating/modifying documentation: Research authoritative sources for all technical claims
  2. After creating/modifying documentation: Create or update verification file
  3. Record all findings: Document sources, confidence levels, and verification status
  4. Mark hardware claims: Flag claims requiring hardware testing with "⚠️ Needs Testing"
  5. Update tracking: Update this index and mark OpenSpec tasks complete

See ../glitchy/AGENTS.md or ../glitchy/CLAUDE.md for detailed agent workflow instructions.

Questions or Issues?

  • Documentation issues: Open an issue on GitHub Issues
  • Verification process: See OpenSpec spec at ../glitchy/openspec/specs/documentation-verification/spec.md
  • Contributing: See Contributing.md (when available) for contribution guidelines

Last Updated: 2026-02-02 Maintained By: Glitchy documentation team

Clone this wiki locally