empirical-validation_skill

Overview

This skill enforces empirical validation: tasks are only marked complete when verifiable evidence is recorded. It removes subjective sign-offs like "code looks correct" and requires concrete outputs such as screenshots, command responses, or build logs. The goal is repeatable, auditable verification attached to each change.

How this skill works

For each change type it specifies the required proof method (UI screenshot, API command output, build output, data query, or file listing). You execute the appropriate action, capture the output, and document the actual evidence in the project journal. If the recorded evidence fails to meet the pre-defined acceptance criteria, the task stays open and failure-handling steps are triggered.

When to use it

• Before marking any task or pull request as done
• After UI changes that affect layout or visuals
• When adding or modifying API endpoints
• For build, configuration, or deployment changes
• When altering data or file contents

Best practices

• Define clear verification criteria before making the change
• Capture raw evidence: full command output or unedited screenshots
• Record evidence under .gsd/JOURNAL.md tied to the task
• Avoid subjective phrases; include concrete success/failure signals
• If verification fails, document in .gsd/STATE.md and create a fix task

Example use cases

• Take a screenshot of a dashboard after a UI tweak and attach it to the task
• Run a curl or PowerShell call against a new API route and paste the response output
• Run the build command and include the build log showing successful compilation
• Query the database or data store to prove a migration produced the expected rows
• List or show file contents after a script changed files to confirm operations