scan-capture-quality-gates
Two scan-capture quality failures — (1) blurry captures sail through with no warning, OR the opposite, a hard blur gate rejects every low-texture subject (plain box, matte fabric, blank wall) and re-prompts "Retake" forever, stranding the user mid-scan; (2) an item auto-names itself with background OCR prose like "Complete the form below and" and the UI renders that guess as high-confidence (green). Use when adding a sharpness/blur accept-reject gate to a camera capture pipeline, or when deriving item/document names from OCR text in a scanning app.
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 1
- Forks
- 1
01 前言 Front Matter
- name
- scan-capture-quality-gates
- description
- Two scan-capture quality failures — (1) blurry captures sail through with no warning, OR the opposite, a hard blur gate rejects every low-texture subject (plain box, matte fabric, blank wall) and re-prompts "Retake" forever, stranding the user mid-scan; (2) an item auto-names itself with background OCR prose like "Complete the form below and" and the UI renders that guess as high-confidence (green). Use when adding a sharpness/blur accept-reject gate to a camera capture pipeline, or when deriving item/document names from OCR text in a scanning app.
02 资源文件 2
- 参考文档references/blur-gate.md1.2 KB
- 参考文档references/ocr-name-scoring.md1.5 KB
03 SKILL.md 正文
Scan Capture Quality Gates: Soft Blur Gate + Auto-Naming Discipline
Symptom
- Blur: captures of low-texture subjects (plain cardboard, matte fabric) fail a hard sharpness check every single attempt — the user is stuck in a retake loop and can never finish the scan. Or, with no gate at all, blurry frames are silently accepted and OCR/recognition downstream degrades.
- Naming: a freshly scanned item appears named with a fragment of background OCR prose — cubby's verbatim case: "Complete the form below and" — and the name renders in the high-confidence (green) style, so the user trusts it.
Root cause
- Sharpness (variance of Laplacian) is a texture metric, not a focus metric. Low-texture subjects score low even in perfect focus, so any hard threshold either passes blur (too low) or strands users (too high). A threshold of 80 rejects legitimate subjects; ~50 is the working value.
- Auto-naming leaks when there are multiple creation entry points: any caller that can pass a name string will eventually pass raw OCR output, and OCR confidence scores are per-glyph, not "is this a name" — prose reads as high-confidence text.
Fix 1 — variance-of-Laplacian as a SOFT gate
Three verdicts, not pass/fail. Auto-accept after a retry budget so low-texture subjects can't strand the user.
nonisolated enum ScanConstants {
static let sharpnessThreshold: Double = 50 // NOT 80 — 80 strands low-texture subjects
static let maxBlurRetries = 2 // then auto-accept
}
nonisolated enum BlurVerdict {
case deliver // sharp enough — accept silently
case warnAllowOverride // soft warn: offer Retake, but keep a "Use Anyway" path
case autoAccept // retry budget exhausted — accept; optionally tag low-detail
}
nonisolated enum BlurGate {
static func verdict(sharpness: Double, retryCount: Int) -> BlurVerdict {
if sharpness >= ScanConstants.sharpnessThreshold { return .deliver }
if retryCount >= ScanConstants.maxBlurRetries { return .autoAccept }
return .warnAllowOverride
}
}
Sharpness itself is measured as the variance of the Laplacian over an 8-bit luma plane (higher = sharper) — a vImage convolution, not a decision rule, so it lives out-of-line.
Read references/blur-gate.md before implementing — laplacianVariance,
the vImage/Accelerate sharpness measurement that feeds verdict above.
Rules: the gate is advisory (warnAllowOverride always keeps a "Use Anyway"
button); never block delivery of the frame itself — gate the accept step.
Fix 2 — auto-naming discipline
ONE creation entry point (callers cannot inject a name), a confidence floor, a sentence-shape reject list, and a hard cap on OCR-derived confidence so OCR guesses never render as verified (green) in the UI.
nonisolated enum NamingConstants {
static let minNameConfidence: Double = 0.5 // below the floor → default name
static let ocrNameConfidenceCap: Double = 0.69 // OCR names never reach "green"
}
nonisolated struct NameCandidate { let text: String; let confidence: Double }
ItemNamer.resolveName is the ONLY way an item gets a name (no caller can
inject a name string): it filters out sentence-like candidates, caps every
surviving candidate's confidence at ocrNameConfidenceCap, takes the best,
and falls back to defaultName if nothing clears minNameConfidence.
isSentenceLike is the prose-fragment reject rule — text is sentence-like
(not a name) if it has more than 6 words, ends in ./,/:, or contains
2+ words from a prose-marker set (the/and/your/please/below/above/complete/
enter/fill). This is what stops fragments like "Complete the form below and"
from becoming an item name.
Read references/ocr-name-scoring.md before implementing — the full
ItemNamer.resolveName and isSentenceLike implementations.
Evidence
- cubby — P4/P6 fix series: soft blur gate (
.deliver/.warnAllowOverride/.autoAccept, threshold lowered 80 → 50, auto-accept after retry budget) and the auto-naming cleanup after background OCR prose ("Complete the form below and") became an item name. - a private document-scanner app — shares the auto-naming discipline; had no sharpness gate at all (the gap this skill closes for new scanning apps).
- Mining report Themes 3.3–3.4 (
docs/superpowers/specs/2026-07-01-ios-mining-report.md).
Related skills
avfoundation-capture-delivery-watchdog— frames never arriving (delivery stalls) is a different failure than frames arriving blurry; gate quality here, watchdog delivery there.vision-barcode-cidetector-fallback— recognition fallbacks on the captured frame; a soft blur gate reduces how often those fallbacks fire.swift6-mainactor-compile-fixes—BlurGate/ItemNamerare pure compute: keep themnonisolatedso they run off-main in the capture pipeline.async-enrichment-silent-loss-outcome-states— downstream on the same scan pipeline: once a frame passes this gate, its async AI enrichment result still needs a visible outcome state, win or lose the merge.
04 同仓库更多 Skills
second-wind
Orchestrate long unattended Claude Code runs across multiple repos with the wind CLI. Use when the user wants to run Claude Code overnight, resume sessions after the 5-hour usage limit, run Claude in many repos at once via tmux, or says "set up second wind", "wind up", "overnight run", "resume after limit", "usage limit orchestrator".
structured-output-adaptive-thinking-token-bloat
A Claude API call using output_config.format (json_schema structured outputs) with thinking:{type:"adaptive"} burns most of its output budget on thinking (observed ~21k of ~24k tokens) without improving JSON quality, making the run up to ~5x more expensive than the same call with thinking omitted — use when calling the Messages API with a json_schema output format for extraction, ranking, classification, or summarization tasks, or when a schema-constrained call's usage.output_tokens is far larger than the returned JSON.
review
Apply a code-review lens to a diff, branch, or file — find correctness bugs, security issues, and quality problems, ranked by severity, with a concrete fix for each. Use when the user says "review this", "review my diff", "check this PR", "look this over before I commit", or "is this safe". Skip when the user wants the code written, not reviewed.
refresh
Rebuild the prompt-craft command registry and usage profile, and print a summary of installed commands and your personalized recommendations. Use when you install or update plugins and want the advisor to pick them up immediately, or say "refresh prompt-craft", "rebuild the command registry".
refactor
Apply a refactoring lens — restructure code without changing behavior, guarded by tests that pass before and after. Use when the user says "refactor", "clean this up", "extract this", "simplify this", "reduce duplication", or "make this readable" on existing working code. Skip when the change is meant to alter behavior (that's a feature or a fix).
plan
Decompose a non-trivial task into an explicit, tracked plan with goals and per-step acceptance criteria before writing code. Use when the user says "plan this", "break this down", "what's the plan", or asks for a multi-step feature/refactor that touches more than one file. Pairs with plan mode. Skip for single-edit changes that need no decomposition.