daymade__claude-code-skills/daymade-audio/transcript-fixer/references/troubleshooting.md

Troubleshooting Guide

Solutions to common issues and error conditions.

Table of Contents

• API Authentication Errors
  • API Key Not Configured
  • Invalid API Key
• Learning System Issues
  • No Suggestions Generated
• Database Issues
  • Database Not Found
  • Database Locked
  • Corrupted Database
  • Missing Tables
• Common Pitfalls
  • 1. Stage Order Confusion
  • 2. Overwriting Imports
  • 3. Ignoring Learned Suggestions
  • 4. Testing on Large Files
  • 5. Manual Database Edits Without Validation
  • 6. Committing .db Files to Git
  • 7. Leftover _stage1.md / _dryrun.md Files
• Validation Commands
  • Quick Health Check
  • Detailed Diagnostics
• Getting Help

API Authentication Errors

API Key Not Configured

Symptom:

❌ API key not configured. Please add it to the config file:
   ~/.transcript-fixer/config.json
   { "api": { "api_key": "your-key" } }
   Or set GLM_API_KEY / ANTHROPIC_API_KEY environment variable.

Solution:

# 1. Make sure the config directory exists
uv run scripts/fix_transcription.py --init

# 2. Edit the config file and set api.api_key
# ~/.transcript-fixer/config.json

Quick override (not recommended for long-term use):

export GLM_API_KEY="your-api-key-here"
# or
export ANTHROPIC_API_KEY="your-api-key-here"

See glm_api_setup.md for detailed API key management.

Invalid API Key

Symptom: API calls fail with 401/403 errors

Solutions:

1. Verify key is correct (copy from https://open.bigmodel.cn/)
2. Check for extra spaces or quotes in the config file
3. Confirm the config uses api.api_key, not a top-level key
4. Regenerate key if compromised
5. Verify API quota hasn't been exceeded

Learning System Issues

No Suggestions Generated

Symptom: Running --review-learned shows no suggestions after multiple corrections.

Requirements:

• Repeated Stage 2 / AI changes saved in correction_history + correction_changes
• Minimum frequency is 3, but the current confidence formula usually needs more repeated occurrences before crossing the 0.8 review threshold
• Learning confidence threshold ≥0.8 (default)

Diagnostic steps:

# Check successful correction history count
sqlite3 ~/.transcript-fixer/corrections.db "SELECT COUNT(*) FROM correction_history WHERE success = 1;"

# If 0, no corrections have been run yet
# If the repeated AI pattern count is still low, run more similar corrections

# Check repeated AI patterns visible to --review-learned
sqlite3 ~/.transcript-fixer/corrections.db "
SELECT c.from_text, c.to_text, h.domain, COUNT(*) AS frequency
FROM correction_changes c
JOIN correction_history h ON h.id = c.history_id
WHERE c.rule_type = 'ai' AND h.success = 1
GROUP BY c.from_text, c.to_text, h.domain
ORDER BY frequency DESC;
"

# Check pending review file produced by --review-learned
cat ~/.transcript-fixer/learned/pending_review.json

# Check system configuration
sqlite3 ~/.transcript-fixer/corrections.db "SELECT key, value FROM system_config WHERE key LIKE 'learning%';"

Solutions:

1. Run more similar correction sessions until repeated AI patterns cross the review threshold
2. Ensure patterns repeat (same error → same correction)
3. Verify database permissions (should be readable/writable)
4. Check correction_history and correction_changes have successful AI entries

Database Issues

Database Not Found

Symptom:

⚠️  Database not found: ~/.transcript-fixer/corrections.db

Solution:

uv run scripts/fix_transcription.py --init

This creates the database with the complete schema.

Database Locked

Symptom:

Error: database is locked

Causes:

• Another process is accessing the database
• Unfinished transaction from crashed process
• File permissions issue

Solutions:

# Check for processes using the database
lsof ~/.transcript-fixer/corrections.db

# If processes found, kill them or wait for completion

# If database is corrupted, backup and recreate
cp ~/.transcript-fixer/corrections.db ~/.transcript-fixer/corrections_backup.db
sqlite3 ~/.transcript-fixer/corrections.db "VACUUM;"

Corrupted Database

Symptom: SQLite errors, integrity check failures

Solutions:

# Check integrity
sqlite3 ~/.transcript-fixer/corrections.db "PRAGMA integrity_check;"

# If corrupted, attempt recovery
sqlite3 ~/.transcript-fixer/corrections.db ".recover" | sqlite3 ~/.transcript-fixer/corrections_new.db

# Replace database with recovered version
mv ~/.transcript-fixer/corrections.db ~/.transcript-fixer/corrections_corrupted.db
mv ~/.transcript-fixer/corrections_new.db ~/.transcript-fixer/corrections.db

Missing Tables

Symptom:

❌ Database missing tables: ['corrections', ...]

Solution: Reinitialize schema (safe, uses IF NOT EXISTS):

uv run scripts/fix_transcription.py --init

Or delete database and reinitialize:

# Backup first
cp ~/.transcript-fixer/corrections.db ~/corrections_backup_$(date +%Y%m%d).db

# Reinitialize
uv run scripts/fix_transcription.py --init

Common Pitfalls

Stage 1 reports "Applied: 0" (usually correct, not a bug)

Safe mode is the default, so Stage 1 only auto-applies low-risk (non-word, high-confidence) corrections. On a clean transcript — or one from a strong ASR engine — there may be no low-risk dictionary hits, so Applied: 0 is expected. Any medium/high-risk candidates are written to *_needs_review.md for you to confirm. To apply every risk level (the pre-safe-mode behavior), pass --apply-all.

1. Native route versus API stages

Problem: Treating the CLI stage number as the skill's recommended route.

Solution: Inside Claude/Codex, run explicit Stage 1 and then Native AI Correction. In agent-less API automation, Stage 2 and Stage 3 both run Stage 1 internally; Stage 3 additionally creates the diff report.

# Agent session (recommended)
uv run scripts/fix_transcription.py --input file.md --stage 1
# Then perform Native AI Correction with this skill loaded.

# Agent-less API route
uv run scripts/fix_transcription.py --input file.md --stage 2
uv run scripts/fix_transcription.py --input file.md --stage 3  # adds diff report

2. Overwriting Imports

Problem: Using --import without --merge overwrites existing corrections.

Solution: Always use --merge flag:

# Wrong: Overwrites existing
uv run scripts/fix_transcription.py --import team.json  # ❌

# Correct: Merges with existing
uv run scripts/fix_transcription.py --import team.json --merge  # ✅

3. Ignoring Learned Suggestions

Problem: Not reviewing learned patterns, missing free optimizations.

Impact: Patterns detected by AI remain expensive (Stage 2) instead of cheap (Stage 1).

Solution: Review suggestions every 3-5 runs:

uv run scripts/fix_transcription.py --review-learned
uv run scripts/fix_transcription.py --approve "错误" "正确"

4. Testing on Large Files

Problem: Testing dictionary changes on large files wastes API quota.

Solution: Start with --stage 1 on small files (100-500 lines):

# Test dictionary changes first
uv run scripts/fix_transcription.py --input small_sample.md --stage 1

# Review output, adjust corrections
# Then run full pipeline
uv run scripts/fix_transcription.py --input large_file.md --stage 3

5. Manual Database Edits Without Validation

Problem: Direct SQL edits might violate schema constraints.

Solution: Always validate after manual changes:

sqlite3 ~/.transcript-fixer/corrections.db
# ... make changes ...
.quit

# Validate
uv run scripts/fix_transcription.py --validate

6. Committing .db Files to Git

Problem: Binary database files in Git cause merge conflicts and bloat repository.

Solution: Use JSON exports for version control:

# .gitignore
*.db
*.db-journal
*.bak

# Export for version control instead
uv run scripts/fix_transcription.py --export corrections_$(date +%Y%m%d).json
git add corrections_*.json

7. Leftover _stage1.md / _dryrun.md Files

Problem: After correction you end up with multiple intermediate files (file_stage1.md, file_dryrun.md, file_changes.md, file_needs_review.md) in the working directory.

Preferred solution: Re-run --stage 1 on the original file.md — plain, without --apply-all (an explicit --apply-all always runs corrections and never takes the promote path, so it won't finalize). If file_stage1.md is newer than file.md, transcript-fixer automatically promotes it to file.md and removes disposable sidecars. It preserves file_changes.md and file_needs_review.md until you explicitly close their review decisions. It skips promotion if file.md has been edited more recently, so it never overwrites your manual changes. This is the recommended finalize path.

uv run scripts/fix_transcription.py --input file.md --stage 1

Manual fallback: In the native AI-correction workflow, edit the original file.md directly, archive it, then delete only the disposable sidecars with a Python one-liner (avoids macOS mv alias hazards):

uv run python -c "
from pathlib import Path
stem = 'file'
for suffix in ['_stage1.md','_dryrun.md','_uncertain.md','_stage2.md','_对比.html']:
    p = Path(f'{stem}{suffix}')
    p.exists() and p.unlink()
"

The manual cleanup also leaves _changes.md and _needs_review.md untouched. Close those with the command built for it rather than by hand:

uv run scripts/fix_transcription.py --close-sidecars --input file.md --dry-run   # verdict only
uv run scripts/fix_transcription.py --close-sidecars --input file.md             # removes on `closed`

It re-reads every entry of both reports against the transcript (ledger line masked) and the review queue for that exact file: closed (exit 0) removes the evidence and stale run outputs; open (exit 1) names each entry that still reads as the original without a verdict and each pending queue id; blocked (exit 2) means a _stage1.md newer than the file is waiting for the plain Stage 1 rerun above, or a report carries entries the tool cannot read (report_unparsed) — inspect that file by hand instead of deleting it. --decide-raw kept_original|skipped --by <who> --note <why> records a verdict through the queue for entries that have no row, so nothing is deleted without an audit trail. A _stage2.md/_dryrun.md newer than the transcript is retained and named; add --discard-unpromoted to drop it.

Why not a bare mv: On macOS, mv is commonly aliased to mv -i. A bare mv file_stage1.md file.md && echo done can skip the overwrite (still exit 0) when the target already exists, leaving the uncorrected file in place. Use the Python one-liner above, or /bin/mv -f, if you must use the shell:

/bin/mv -f file_stage1.md file.md          # /bin/mv ignores the alias; -f forces overwrite
grep -c '<the-WRONG-form-you-replaced>' file.md   # must print 0

Verify the claim you need: absence of the old form. Presence of the corrected term is not evidence that this occurrence changed, because the correct term may already appear elsewhere in the transcript. A nonzero old-form count means the promotion or replacement is incomplete.

Validation Commands

Quick Health Check

uv run scripts/fix_transcription.py --validate

Detailed Diagnostics

# Check database integrity
sqlite3 ~/.transcript-fixer/corrections.db "PRAGMA integrity_check;"

# Check table counts
sqlite3 ~/.transcript-fixer/corrections.db "
SELECT 'corrections' as table_name, COUNT(*) as count FROM corrections
UNION ALL
SELECT 'context_rules', COUNT(*) FROM context_rules
UNION ALL
SELECT 'learned_suggestions', COUNT(*) FROM learned_suggestions
UNION ALL
SELECT 'correction_history', COUNT(*) FROM correction_history;
"

# Check configuration
sqlite3 ~/.transcript-fixer/corrections.db "SELECT * FROM system_config;"

Getting Help

If issues persist:

1. Run --validate to collect diagnostic information
2. Check correction_history and audit_log tables for errors
3. Review references/file_formats.md for schema details
4. Check references/architecture.md for component details
5. Verify Python and uv versions are up to date

For database corruption, automatic backups are created before migrations. Check for .bak files in ~/.transcript-fixer/.