--- name: video-editing-docs-and-writing description: Load when creating, correcting, reviewing, or retiring this repository's README, plans, runbooks, diagrams, ADRs, API/configuration references, release evidence, operational documents, prompts, or milestone checklists; also load when a command, path, status, production-readiness claim, or implementation description in docs may have drifted from source. --- # Video Editing Documentation And Writing ## Purpose Write documentation that a zero-context mid-level engineer or Sonnet-class model can execute without guessing. Separate implemented behavior from target architecture, and make every important claim traceable to source, a test, a measurement, or an approved decision. Treat repository facts in this skill as verified on **2026-07-21**. The Fortune 500 reference-architecture requirements are the target acceptance standard; they do not describe the repository's current state. Compact glossary: **SBOM** is Software Bill of Materials; **SLI** is service-level indicator; **SLO** is service-level objective; **RTO** is Recovery Time Objective; **RPO** is Recovery Point Objective; **OCI** is Open Container Initiative image format. ## When not to use this skill | Need | Load instead | |---|---| | Decide whether a behavior/default may change or a production claim may be promoted | `video-editing-change-control` | | Find the implemented architecture and load-bearing invariants | `video-editing-architecture-contract` | | Catalog or change properties, profiles, flags, and guards | `video-editing-config-and-flags` | | Recreate the toolchain or prove a clean build | `video-editing-build-and-env` | | Start schedulers, render media, or locate runtime artifacts | `video-editing-run-and-operate` | | Define tests, creative-quality evidence, or promotion thresholds | `video-editing-validation-and-qa` | | Diagnose a symptom or interpret diagnostic output | `video-editing-debugging-playbook` and `video-editing-diagnostics-and-tooling` | | Explain why an old decision or failure happened | `video-editing-failure-archaeology` | Do not use documentation to authorize a change, bypass approval, or turn intent into evidence. ## Apply the documentation safety boundary Enforce these rules in every document, example, diagram, and generated artifact: 1. Do not instruct runtime startup to download dependencies or model weights. Do not prescribe external AI services, unapproved network access, unlicensed assets, placeholder silence/tones, or unapproved rendering. 2. Do not present a production-facing default change as a documentation correction. Route the implementation and its documentation through `video-editing-change-control`. 3. Mark the current automatic bootstrap/download, heuristic fallback, placeholder audio, and approval-bypass behavior as defects or development-only behavior, never as approved production practice. 4. Do not paste secrets, credentials, private hosts, user home paths, local virtual environments, proprietary footage, or unredacted production payloads into documentation. 5. Do not claim production-ready, secure, scalable, reproducible, cinematic, licensed, validated, signed off, or complete without the required evidence and approval. 6. Treat documentation-only work as C0 only when it cannot change runtime/build behavior. A command, configuration, API, schema, deployment, or operational contract correction that reveals or requires behavior change inherits the applicable C2/C3 route. ## Start from the current repository truth Run these read-only checks from the repository root before writing: ```bash git status --short git log -10 --oneline --decorate git ls-files 'docs/**' 'src/main/resources/**' 'tools/**' 'dashboards/**' pom.xml | sort find .claude/skills -maxdepth 2 -name SKILL.md -print | sort find src/main/java src/test/java -type f | sort ``` As of 2026-07-21: | Current fact | Documentation consequence | |---|---| | There is no tracked `README.md`, contributor guide, OpenAPI document, ADR set, architecture diagram, CI workflow, container definition, or deployment definition. | List each as missing target work. Never write “see” or “validated by” one of these artifacts. | | `docs/` contains plans, prompts, runbooks, operating checklists, benchmark baselines, and readiness templates without an explicit authority hierarchy. | Classify each document before relying on it. A plan is not an implementation contract. | | `pom.xml` uses Java 21 and Spring Boot 3.3.2; no Maven Wrapper is tracked. | State implemented versions and current prerequisites. Do not call Spring Boot 3.3.2 “latest” without a separately approved, date-stamped primary-source check. | | Base `application.yml` enables ingestion schedulers and local-worker auto-start, while highlight rendering defaults off and approval defaults on; current CV/bootstrap scripts may install packages or resolve models. | Do not recommend a plain startup as a harmless documentation-verification command. Use the operating/build siblings and explicit safe overrides. | | `application-jpa.properties` uses H2 in PostgreSQL compatibility mode. | Do not describe current repository integration tests as real PostgreSQL/Testcontainers evidence. | | `production-cinematic-highlight-editing-plan.md` checks all milestones, while `highlight-rendering-gap-closure-plan.md` remains unchecked and `cinematic-highlight-operator-checklist.md` says rendering is not wired. Current source now contains `HighlightDirectorFlowService` and `HighlightFfmpegRenderer`. | Label the documents contradictory/stale until source, tests, and an executed flow establish one current description. Do not settle the conflict by trusting the newest prose or a checkbox. | | `video-clipping-service-implementation-plan.md` checks “Load-test signoff,” while `load-test-signoff.md` says execution evidence is pending and no load generator/results are checked in. | State “documentation template exists; load signoff unvalidated.” | | `input-folder-scheduler-plan.md` names a nonexistent `FolderSchedulerProperties.java`; properties are nested under `VideoClippingProperties`. | Correct or label the proposed path; do not send an engineer to it. | | Existing benchmark documents describe local baselines and generated files under `target/`. | Preserve environment/date/commit qualifiers. Never convert a workstation baseline into an SLO or production capacity claim. | ## Use the authority hierarchy Resolve conflicts in this order. Higher authority establishes current behavior; it does not automatically prove quality or production readiness. | Rank | Authority | What it can establish | |---:|---|---| | 1 | Executable source, migrations, packaged resource files, build manifest | What the checked-out artifact is designed to do and its configured defaults. | | 2 | Deterministic tests and retained command output tied to a commit/environment | What was exercised, within the test's actual assertions and prerequisites. | | 3 | Versioned generated contract or measured report tied to its generator and inputs | The generated schema/measurement, if regeneration matches. `target/` alone is disposable, not a record. | | 4 | Approved ADR, API contract, operations record, or release evidence | The accepted decision/contract for its stated scope and date. These record approval, not code existence. | | 5 | Current reference/runbook checked against ranks 1-4 | How to understand or operate the verified behavior. | | 6 | Plan, prompt, issue-shaped note, checklist, proposed diagram | Intent. A checked box still needs evidence. | | 7 | Historical or retired document | Context only; never an operating instruction. | When code and an approved contract differ, report the mismatch. Do not silently rewrite the contract to match code or treat the code as approved. ## Give each fact one home Keep the detailed fact in one canonical home. Cross-reference it elsewhere with a short reason; do not copy tables that will drift. | Fact | Current/target canonical home | Cross-reference rule | |---|---|---| | Entry point, prerequisites, safe local quick start, repository map | **TARGET:** `README.md` (currently absent) | Other docs link to the relevant README heading once it exists. Until then, state that the entry-point doc is missing. | | Dependency versions and build plugin behavior | `pom.xml`; explanation in build/environment docs | Never duplicate a version without “verified YYYY-MM-DD” and a recheck command. | | Runtime property defaults and profile overrides | Source/resources; `video-editing-config-and-flags` is the maintained explanatory catalog | Runbooks name only the few overrides needed for that procedure and link to the catalog. | | REST resources, schemas, status/errors, compatibility | **TARGET:** versioned OpenAPI document (currently absent) | Controller prose is an implementation note, not the public contract. | | Database schema and migration order | `src/main/resources/db/migration/` | Data/runbook docs link to migrations and explain operation; do not reproduce full DDL. | | Module responsibilities and dependency direction | **TARGET:** architecture overview plus context/module diagrams (currently absent) | ADRs explain decisions; code maps and README link to the overview. | | Important design decision and alternatives | **TARGET:** one immutable-numbered ADR per decision (currently absent) | Plans and PRs link to the ADR; do not restate the decision history. | | Alert response and recovery procedure | `docs/runbooks.md` or one linked specialized runbook | Alert definitions link to the procedure; dashboards do not duplicate it. | | Test and quality acceptance | `video-editing-validation-and-qa` until a tracked testing strategy exists | Plans list intended coverage only; releases link to retained evidence. | | Historical failure | `video-editing-failure-archaeology` | Current docs link to the incident/lesson rather than retelling it. | | Change gates and promotion | `video-editing-change-control` | Every behavior-changing plan routes to it. | | Release-specific versions, evidence, approvals, known limits | **TARGET:** immutable release record (currently absent) | README/runbooks link to the current supported release record. | Propose any new canonical path through documentation review. Do not create a second home merely because the target home is absent. ## Label status and evidence explicitly Put this block near the top of every maintained reference, runbook, plan, diagram, or report: ```text Status: CURRENT | TARGET | CANDIDATE | HISTORICAL Scope: Last verified: YYYY-MM-DD Applies to: commit | release | proposed Owner: Evidence: Next review: YYYY-MM-DD | event that forces review ``` Use labels strictly: | Label | Meaning | Required wording | |---|---|---| | `CURRENT` | Matches source and has evidence for the bounded claim. | Say exactly what was verified, where, when, and on which environment. | | `TARGET` | Accepted requirement not yet demonstrated. | Use “must,” “target,” or “not implemented”; never “supports” or “provides.” | | `CANDIDATE` | Proposed/hypothesized and awaiting decision or evidence. | Name owner, experiment/gate, and expiry or revisit condition. | | `HISTORICAL` | Superseded, rejected, or incident context. | Name replacement/status and prohibit operational use. | Qualify evidence separately: `SOURCE-INSPECTED`, `TESTED`, `MEASURED`, `REVIEWED`, or `UNVERIFIED`. A source-inspected branch is not tested; a passing structure test is not cinematic quality; a document checklist is not execution evidence. Never use a bare `[x]` for a milestone. Use a table: ```markdown | Milestone | Status | Evidence | Last verified | Remaining gate | |---|---|---|---|---| | Local-model voiceover | TARGET | `NONE` | 2026-07-21 | Offline licensed model; intelligibility and timing measurements; approval | ``` ## Follow the maintenance workflow 1. **Classify the document.** Choose reference, runbook, contract, decision, plan, evidence report, prompt, or historical record. Do not combine target design and current operation without visibly separate sections. 2. **Select one fact owner.** Use the table above. If the home is missing, add it to the backlog; do not scatter temporary copies. 3. **Build a claim ledger.** For each normative/current sentence, record claim, status, evidence, verification command, and volatility. 4. **Inspect implementation.** Read the relevant source, resources, tests, migrations, and history. A class name proves existence only, not wiring or success. 5. **Write in imperative order.** State purpose and safety boundary, prerequisites, exact steps, expected observations, failure branches, rollback/stop condition, and evidence to retain. 6. **Synchronize all affected surfaces.** Use the matrices below. If an expected contract is absent, state the gap instead of inventing it. 7. **Verify every literal.** Check paths, class names, commands, flags, defaults, endpoint mappings, filenames, event names, and output fields against the current tree. 8. **Run non-mutating audits.** Do not start schedulers, bootstrap workers, download dependencies/models, render, use network, or mutate Git merely to validate prose. 9. **Route claims.** Send behavior/default changes and production-readiness claims through `video-editing-change-control`; attach validation evidence rather than declaring success in prose. 10. **Record maintenance.** Date volatile facts and add one-line re-verification commands at the end. ## Synchronize contracts ### Configuration For any property statement, compare all applicable locations: ```bash rg -n 'class VideoClippingProperties|@ConfigurationProperties|enabled|auto-start|render-enabled|require.*approval|fallback|strict-runtime' src/main/java/org/example/videoclips/config src/main/resources src/test rg -n 'VIDEO_EDITING_|FOLDER_SCHEDULER_|video-clipping\.' docs tools src/main/resources src/main/java ``` Check the Java default, packaged default, profile override, environment mapping, validation, component guard, tests, operational risk, and rollback. Defer the full catalog to `video-editing-config-and-flags`. ### API For any endpoint statement, compare controllers, DTOs, exception mapping, application service, and API tests: ```bash rg -n '@(RequestMapping|GetMapping|PostMapping|PutMapping|PatchMapping|DeleteMapping)|ProblemDetail' src/main/java/org/example/videoclips/api find src/main/java/org/example/videoclips/api/dto src/test/java/org/example/videoclips/api -type f | sort find . -maxdepth 3 -type f \( -iname '*openapi*' -o -iname '*swagger*' \) -print ``` The last command currently returns nothing. Do not claim OpenAPI publication, build validation, compatibility checking, authentication, pagination, or idempotency unless separately evidenced. ### Runtime file layout For any input/output path, compare packaged configuration, folder-contract/constants, initializer, store, scheduler, tests, and the runbook: ```bash rg -n 'Path |resolve\(|createDirectories|source-directory|working-directory|processed-directory|rejected-directory|project-directory|highlight-project-directory' src/main src/test rg -n 'input/|output/|target/|project.json|edit-plan.json|render-manifest.json|qa-report.json' docs ``` Distinguish repository-relative defaults, configurable paths, generated/disposable `target/` output, and production volume contracts. Never use a private absolute path. ### Operations, metrics, and deployment Compare event/metric source with alert, dashboard, and runbook names: ```bash rg -n 'event=|Counter|Timer|Gauge|Observation|MeterRegistry|HealthIndicator' src/main/java rg -n 'video_clipping_|http_server_|event=|/actuator/' docs dashboards find . -maxdepth 3 -type f \( -iname 'Dockerfile*' -o -iname '*compose*' -o -iname '*helm*' -o -iname '*k8s*' \) -print ``` The deployment-file search currently returns nothing. Label Kubernetes, HPA/KEDA, cloud, backup, restore, and rollout material as target guidance or environment procedure unless executed evidence exists. ## Run the documentation audits ### Broken or stale path audit ```bash git ls-files | sort > /tmp/video-editing-tracked-files.txt rg -n '`(src|docs|tools|dashboards)/[^`]+`|`pom.xml`|`README.md`' docs rg -n 'FolderSchedulerProperties|README|openapi|swagger|ADR|Dockerfile|compose|helm|k8s' docs find docs src/main/resources tools dashboards -type f -print | sort ``` Inspect every literal path against the tracked-file list. Treat placeholders such as `` as patterns, not files. Flag references to generated `target/` artifacts unless the document provides a reproducible generator and explicitly calls them disposable. ### Milestone and overclaim audit ```bash rg -n '^- \[[ xX]\]|complete|implemented|production[- ]ready|validated|verified|signed off|supports|automatic today' docs rg -n 'pending|not implemented|not yet|still manual|limitation|known gap|unchecked|heuristic|fallback|placeholder|proposed|intended' docs git log --format='%h %ad %s' --date=short -- docs ``` Pair every positive claim with contrary qualifiers and implementation evidence. Mandatory current findings include the highlight-plan/rendering contradiction and the load-signoff contradiction listed above. Preserve old milestones as `HISTORICAL` when useful; do not erase a failed or superseded approach. ### Source drift audit ```bash git diff --name-only HEAD -- pom.xml src/main src/test tools dashboards docs rg -n '|spring-boot-starter-parent||' pom.xml rg -n '^video-clipping:|^[[:space:]]+[a-z0-9-]+:' src/main/resources/application*.yml find src/main/resources/db/migration -maxdepth 1 -type f -print | sort find src/test/java -name '*Test.java' -print | sort ``` When code changes without docs, identify the canonical document affected. When docs change without code, verify that they remain intent-only or accurately describe existing behavior. Do not use line/test counts as stable claims unless date-stamped and regenerated. ### Command and example audit For each command, verify executable, working directory, required environment, side effects, network behavior, expected exit/result, and cleanup. Prefer a focused read-only or test command. Never recommend `mvn spring-boot:run` as a documentation lint because current defaults can consume input, start workers, install dependencies, resolve models, and render. Use these syntax/content checks after editing Markdown: ```bash git diff --check -- .claude/skills docs README.md 2>/dev/null rg -n '^```' .claude/skills docs rg -n '[/]Users/|[/]home/|[A-Za-z]:\\\\|api[_-]?key|secret|password|token' .claude/skills docs ``` Review fence pairs manually or with an approved Markdown linter if one is later added. No Markdown lint/build is configured in `pom.xml` today. ## Use these document templates ### ADR ```markdown # ADR-NNN: Status: CANDIDATE | ACCEPTED | SUPERSEDED Date: YYYY-MM-DD Owners: ## Context Requirement, constraints, current evidence, and trust boundaries. ## Decision Selected approach and dependency direction. ## Alternatives Considered Option, rejection reason, and evidence. ## Consequences Benefits, trade-offs, operational consequences, and security implications. ## Verification Tests, measurements, scans, and approval required. ## Revisit Conditions Specific signal, date, dependency change, or failed threshold. ``` For every major decision include the requirement, selected approach, alternatives, benefits/trade-offs, operational consequences, security implications, verification, and revisit conditions. Do not mark an ADR accepted without the authority required by change control. ### Incident record ```markdown # Incident: Status: OPEN | MITIGATED | RESOLVED Window/Environment/Build: Impact: Detection: Evidence preserved: Timeline: Root cause: Contributing conditions: Rejected hypotheses: Mitigation and recovery: Corrective actions: Recurrence test: ``` Move the durable symptom -> cause -> evidence -> status lesson into `video-editing-failure-archaeology`; keep sensitive operational data outside the repository. ### Operational runbook ```markdown # Runbook Status/Owner/Last verified/Applies to: Trigger and user impact: Safety boundary: Prerequisites: Triage: expected result -> branch> Mitigation: Verification: Escalation: Rollback/Recovery: Known gaps: ``` Never place an unapproved database mutation, file deletion, scheduler start, render, dependency/model download, or production-default change in a “quick fix.” ### Diagram Use text-source diagrams that can be reviewed in diffs. Label every box as implemented, target, or external; show trust boundaries, protocols, state stores, local model processes, ownership, and dependency arrows. A context diagram shows users/external systems. A module/container diagram shows deployable/process/module boundaries. A runtime-flow diagram shows ordering, state transitions, failure paths, approval, retry/idempotency, and observability. Validate every node against source or an accepted ADR. Do not draw target PostgreSQL, OAuth/OIDC, OpenTelemetry, containers, Kubernetes, model registry, or cloud services as current. ### Release record ```markdown # Release Commit/artifact digest/build provenance/SBOM: Environment promotions and approvals: Schema/API/config/default deltas: new> Model/asset versions, checksums, origins, licenses: Security and dependency scan result: Test/quality/load/resilience evidence: Known limitations/risk acceptances/expiry: Migration/rollback/smoke verification: Owners/RTO/RPO/support window: ``` Do not create release notes from commit subjects alone. Verify user-visible behavior and retained evidence. ## Maintain the Fortune 500 documentation backlog Record these as **TARGET/MISSING**, not complete. Create them only through reviewed work; keep one fact home as defined above. | Priority | Required artifact | Current evidence/gap | |---:|---|---| | P0 | README with prerequisites, safe local setup, architecture map, test/config/deploy links, representative API requests, and troubleshooting | No `README.md`. | | P0 | Versioned OpenAPI plus build validation and breaking-change gate | Controllers/tests exist; no OpenAPI artifact/plugin. | | P0 | Architecture overview: context, modules/dependency direction, and critical runtime flows | No architecture diagram or enforced module document. | | P0 | Security/threat-model summary: trust boundaries, assets, threats, mitigations, auth, secrets, audit/redaction | No threat model; Spring Security is not in the current POM. | | P0 | Testing strategy and evidence inventory: unit, architecture, slices, PostgreSQL/Testcontainers, contracts, E2E, mutation, coverage | Tests exist, but no comprehensive strategy or required enterprise gates. | | P0 | Local development guide for macOS and reproducible Linux/VPS/cloud build/runtime | Existing runbooks are workflow-specific; clean-checkout reproducibility is not established. | | P0 | Deployment/operations guide: immutable OCI artifact, config/secrets, health, graceful shutdown, resources, rolling deploy, rollback/roll-forward | No image or deployment definitions; existing operational docs are templates/guidance. | | P0 | Local-model/media supply-chain and licensing record | Current workers can bootstrap/download/fallback; model and asset provenance is not production-certified. | | P1 | Configuration reference generated/checked against typed properties, resources, profiles, guards, and secret policy | Use `video-editing-config-and-flags` now; no product-facing reference artifact. | | P1 | ADR index and ADRs for modular-monolith boundaries, persistence/queue/storage, local model isolation, approval gate, file contracts, observability, and deployment | No ADRs. | | P1 | Observability/SLI/alert/runbook map and dashboard validation | Docs/dashboard exist; traces, deployed evidence, owners, and full business SLIs remain incomplete. | | P1 | Data operations: schema strategy, immutable migrations, UTC/concurrency/index decisions, backup/restore, retention, RTO/RPO | Flyway V1-V6 and procedure prose exist; no real PostgreSQL restore evidence or assigned RTO/RPO. | | P1 | CI/CD, quality-gate, dependency-update, branch-review, SBOM/signing/provenance, and promotion policy | No CI workflow or release provenance record. | | P1 | Performance/capacity methodology and executed workload reports | Local baselines exist; no checked-in production-like load generator/signoff. | | P2 | Ownership/contribution policy, glossary, support/escalation map, changelog/release records, and documentation review cadence | No contributor/ownership/release docs found. | Treat existing plans as inputs to this backlog, not substitutes for these records. ## Apply the house style - Address the operator directly with imperative verbs: “Run,” “Verify,” “Stop,” and “Escalate.” - Define each project/domain term once. Link to its owner thereafter. - Put prerequisites before commands and expected observations immediately after them. - Give discriminating branches: “If X, do Y; if not, stop and collect Z.” - Use repository-relative paths and exact case. Put literals in backticks. - Use UTC for incidents/releases; use ISO `YYYY-MM-DD` for volatile fact dates. - Separate `CURRENT`, `TARGET`, `CANDIDATE`, and `HISTORICAL` content visibly. - Use tables for catalogs/comparisons and checklists for actions, not for proof. - State negative facts plainly: “No OpenAPI artifact exists,” not “OpenAPI is forthcoming.” - Keep examples realistic but sanitized. Label illustrative IDs, hosts, values, and outputs. - Explain rationale and evidence; do not narrate obvious syntax or advertise the architecture. - Preserve limitations, failed experiments, and uncertainty. Write `UNKNOWN` rather than guessing. ## Definition of done for a documentation change - [ ] The document has one type, owner, status, scope, date, applicable commit/release, evidence, and review trigger. - [ ] Every current claim is bounded and evidenced; every target/candidate statement is labeled. - [ ] The fact has one canonical home and sibling documents cross-reference rather than duplicate it. - [ ] Paths, commands, config values, endpoints, event/metric names, file layouts, versions, and tests were rechecked. - [ ] Commands state prerequisites, side effects, expected observations, failure branch, and avoid prohibited actions. - [ ] API/config/schema/file-layout/operations surfaces were synchronized or an explicit drift issue was recorded. - [ ] Security, licensing, privacy, approval, and network boundaries are explicit where applicable. - [ ] Behavior/default/production claims went through `video-editing-change-control` with evidence from the correct sibling skill. - [ ] No private path, secret, proprietary input, generated-only source, or unverified production claim was embedded. - [ ] `git diff --check` and the audits above pass or each remaining finding is recorded with owner/status. ## Provenance and maintenance Repository baseline and volatile findings were source-inspected on **2026-07-21**. Re-verify before use: ```bash git log -1 --format='%H %cs %s' test -f README.md; find .github -maxdepth 3 -type f -print 2>/dev/null; find . -maxdepth 3 -type f \( -iname '*openapi*' -o -iname '*adr*' -o -iname 'Dockerfile*' -o -iname '*compose*' \) -not -path './target/*' -print rg -n '^- \[[ xX]\]|production[- ]ready|signed off|execution evidence pending|still manual|not wired|limitation|known gap' docs rg -n 'FolderSchedulerProperties|HighlightDirectorFlowService|HighlightFfmpegRenderer|render-enabled|require-director-approval' docs src/main src/test rg -n '@(RequestMapping|GetMapping|PostMapping|PutMapping|PatchMapping|DeleteMapping)|ProblemDetail' src/main/java/org/example/videoclips/api rg -n '|spring-boot-starter-parent|jacoco-maven-plugin' pom.xml find src/main/resources/db/migration -maxdepth 1 -type f -print | sort git diff --check -- .claude/skills docs README.md 2>/dev/null ```