vp-k/flutter-craft/flutter-verification

Flutter Verification Before Completion

Overview

Claiming work is complete without verification is dishonesty, not efficiency.

Core principle: Evidence before claims, always.

Violating the letter of this rule is violating the spirit of this rule.

The Iron Law

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

If you haven't run the verification command in this message, you cannot claim it passes.

Note: This is an agent-discipline convention enforced by the workflow, not a mechanical gate — flutter-craft ships only a SessionStart hook, so nothing blocks a premature completion claim at the tool level. The rule holds only insofar as the agent follows it.

Flutter Verification Commands

1. Static Analysis (Always Required)

flutter analyze

Expected output:

Analyzing <project>...
No issues found!

If issues found:

Analyzing <project>...
   info • ... • lib/path/file.dart:42:10 • ...
   warning • ... • lib/path/file.dart:50:5 • ...
 
3 issues found. (1 warning, 2 hints)

2. Unit Tests (Priority 1 & 2)

# All tests
flutter test
 
# Specific feature tests
flutter test test/features/<feature>/
 
# Specific test file
flutter test test/features/<feature>/data/repositories/user_repository_test.dart

Expected output:

00:05 +12: All tests passed!

If tests fail:

00:03 +10 -2: Some tests failed.

3. Build Verification (once at the finishing stage — not on every completion claim)

Run against the project's actual target platform only:

# Android
flutter build apk --debug
 
# iOS (macOS only)
flutter build ios --debug --no-codesign
 
# Web
flutter build web
 
# Desktop
flutter build windows / macos / linux

Expected output (example, Android):

✓ Built build/app/outputs/flutter-apk/app-debug.apk (XX.XMB)

4. Format Check (Optional)

dart format --set-exit-if-changed lib/

The Gate Function

BEFORE claiming any status or expressing satisfaction:
 
1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
   - If NO: State actual status with evidence
   - If YES: State claim WITH evidence
5. ONLY THEN: Make the claim
 
Skip any step = lying, not verifying

Common Flutter Failures

Red Flags - STOP

If you catch yourself thinking or saying:

• "should work now"
• "probably passes"
• "looks correct"
• "I'm confident"
• "just this once"
• "analyze passed, so build will work"
• "the code is right"
• ANY wording implying success without running verification

STOP. Run the verification command.

Verification Checklist

Before claiming completion:

### Verification Results
 
**Static Analysis:**

$ flutter analyze Analyzing flutter_app... No issues found!

✅ Passed
 
**Unit Tests:**

$ flutter test test/features/<feature>/ 00:05 +12: All tests passed!

✅ 12/12 passed
 
**Build:**

$ flutter build apk --debug ✓ Built build/app/outputs/flutter-apk/app-debug.apk

✅ Built successfully
 
**Ready to claim completion.**

Key Patterns

Static Analysis:

✅ [Run flutter analyze] [See: No issues found!] "Analysis passes"
❌ "Code looks clean" / "I wrote it correctly"

Tests:

✅ [Run flutter test] [See: 34/34 pass] "All tests pass"
❌ "Should pass now" / "Tests look correct"

Build:

✅ [Run flutter build] [See: Built successfully] "Build passes"
❌ "Analyze passed" (analyze doesn't check build)

Feature completion:

✅ Re-read plan → Verify each requirement → Run all verifications → Report
❌ "Tests pass, feature complete"

Rationalization Prevention

Why This Matters

• Trust: If you claim "tests pass" without running them, trust is broken
• Time: False completion → redirect → rework wastes everyone's time
• Quality: Unverified code may crash in production
• Integrity: Honesty is a core value

When To Apply

ALWAYS before:

• ANY variation of success/completion claims
• ANY expression of satisfaction ("Done!", "Fixed!", "Works!")
• Committing code
• Creating PRs
• Moving to next task
• Reporting to user

The Bottom Line

No shortcuts for verification.

Run the command. Read the output. THEN claim the result.

# Always run these before claiming completion:
flutter analyze
flutter test

This is non-negotiable.

A full flutter build is NOT required at every completion claim — it is slow and platform-dependent. It runs once, in flutter-finishing, against the project's actual target platform.

5. Visual Verification (Optional — Flutter Web)

For work that includes UI changes, perform visual verification if the design-polish plugin is installed. If it is not installed, skip this step (SOFT_FAIL).

Prerequisites

• design-polish plugin installed (~/.claude/plugins/marketplaces/design-polish or ~/.claude/plugins/design-polish)
• scripts/capture.cjs exists
• Node.js + npx available

Procedure

1. Build Flutter Web

``bash flutter build web ``

1. Serve the build output locally

``bash npx serve build/web -l 3000 & SERVER_PID=$! ``

1. Screenshot + WCAG check

``bash BASE_URL=http://localhost:3000 node <design-polish-path>/scripts/capture.cjs --wcag / ``

1. Check the results

• .design-polish/health-score.json: design health score (0-100)
• .design-polish/accessibility/wcag-report.json: WCAG violations
• .design-polish/screenshots/current-main.png: current screenshot

1. Stop the server

``bash kill $SERVER_PID 2>/dev/null ``

Verdict Criteria

Evidence Record

**Visual Verification:**
-Health Score: 85/100
-WCAG: 0 violations
-Screenshot: .design-polish/screenshots/current-main.png
✅ Visual check passed (or ⚠️ skipped / ⚠️ warnings found)