video_editing_poc/.claude/skills/video-editing-external-positioning/SKILL.md

name

description

video-editing-external-positioning

Load this skill when drafting or reviewing public claims, release notes, papers, architecture case studies, model cards, benchmark comparisons, production-readiness statements, Fortune 500 reference-architecture assessments, or claims that this video-editing service is cinematic, local, offline, secure, scalable, reproducible, or state of the art. Use it to assemble the evidence package and prevent repository capabilities from being overstated.

Position This Project Externally

Purpose

Turn repository facts into claims that an independent reviewer can reproduce. Treat code, plans, tests, executed measurements, and accepted claims as different evidence levels.

Use the repository state and rules dated 2026-07-21:

• The target is a production-grade reference architecture suitable for a Fortune 500 engineering organization.
• The hardest live problem is identifying highlights and editing them to high cinematic quality with production-ready visuals, sound, music, and voiceover using models packaged inside the service runtime.
• Automatic dependency or model downloads, external AI services, unlicensed assets, placeholder silence or tones, unapproved rendering, network access, and changes to production-facing defaults are prohibited.
• Required environments are macOS development, Linux/VPS production, and cloud infrastructure.

Do not weaken these rules to make a release or paper easier to announce.

When Not To Use This Skill

Need	Load this sibling instead
Classify, gate, or approve a code/config change	video-editing-change-control
Decide whether tests and measurements meet acceptance thresholds	video-editing-validation-and-qa
Turn a hypothesis into an experiment and survive adversarial review	video-editing-research-methodology
Plan work on cinematic highlight quality	video-editing-cinematic-highlights-campaign
Document build prerequisites or reproduce the runtime	video-editing-build-and-env
Maintain repository documentation rather than external claims	video-editing-docs-and-writing

Do not use this skill to approve a claim about your own change. Require an independent reviewer and the gates below.

SBOM means Software Bill of Materials.

Define The Claim Vocabulary

Use these terms consistently:

Term	Meaning here
Technique	A known engineering method used by the repository, such as FFmpeg filtering, Flyway migrations, ports/adapters, or Micrometer metrics. Its presence is not novelty.
Capability	Behavior demonstrated by code plus an executable test or retained run artifact for a named commit and environment.
Candidate	A plausible design, result, or novelty that has not met its evidence gate.
Claim	A bounded statement with named scope, baseline, metric, threshold, commit, environment, and evidence owner.
Evidence package	Immutable inputs, commands, outputs, measurements, provenance, negative results, and independent review needed to audit a claim.
Production-ready	Verified against the entire production definition of done, not merely able to start or render an MP4.
Local	Computation executes on the declared host or contained runtime. This does not imply offline, bundled models, no telemetry, or no download.
Offline	A clean, isolated run completes with egress denied and all dependencies, weights, and assets supplied by an approved artifact.
Reproducible	An independent operator can recreate a declared result from an immutable revision and artifact set within stated tolerances. Do not imply byte-for-byte identity unless tested.
Cinematic quality	A preregistered technical and blinded-human evaluation passes. File validity or the presence of effects is insufficient.
State of the art (SOTA)	A statistically defensible improvement over current, relevant external baselines established from approved primary evidence.

Start From The Current Claim Ledger

Treat this table as the default posture until newer retained evidence replaces it.

Area	Repository fact	Allowed wording	Forbidden inference
Platform	pom.xml declares Java 21, Spring Boot 3.3.2, Maven, PostgreSQL, Flyway, S3, Actuator, Prometheus, H2, and test dependencies.	"The repository currently declares ..."	"Latest," "supported," "locked," "hardened," or "vulnerability-free." No approved current external version/vulnerability evidence exists.
Editing	Code contains source analysis, candidate/director flow, FFmpeg renderers, local asset integration, manifests, and QA report types.	"Implements an in-repository cinematic highlight pipeline candidate."	"Produces production-ready cinematic edits."
Visual models	A local HTTP CV adapter and worker exist; configuration defaults to local-cv and permits heuristic fallback.	"Supports a local CV worker adapter with configurable heuristic fallback."	"All highlight decisions are model-driven," "fully local," or "offline."
Audio models	tools/local_asset_worker.py invokes Piper when configured and AudioCraft model loaders for music/SFX.	"Contains adapters for local TTS and generative audio runtimes."	"Models reside in the service runtime," "no downloads," or "production voice/music/SFX."
Fallbacks	Historical output may contain silence, tones, or host speech. The 2026-07-21 working tree removes those success paths and rejects missing requested assets.	Identify the exact source revision and asset provenance.	Any cinematic or real-asset claim for an older output or an output without model/asset manifests.
Downloads	Worker bootstrap scripts run unpinned pip install; model APIs can resolve named weights. Local CV documentation says startup may download dependencies/YOLO weights.	"Current bootstrap paths may access package/model networks."	"Hermetic," "offline," "dependency-locked," or "no automatic downloads."
Approval	Highlight rendering now defaults off and approval on; the separate local-director profile also requires a flag. The REST edit-render endpoint and bare flag design still lack production authorization.	State the exact workflow, effective configuration, and approval limitation.	"All rendering requires authenticated, digest-bound human approval."
QA	HighlightFfmpegRenderer.buildQaReport now probes duration, black ranges, long silence, and sample peaks; asset/mastering and overlay checks remain structural or plan-level.	"Writes a technical QA report with measured defect probes and structural checks."	"QA-certified," "validated loudness," "raster-safe overlays," or "measured cinematic quality."
Tests	The suite contains unit, Spring, and FFmpeg-backed tests. A 2026-07-21 offline working-tree mvn -q -o verify run passed 245 tests in 62 test classes.	State the command, tree state, date, and attached report.	"Clean-checkout reproducible," "network-isolated," or cross-platform. An earlier clean archived checkout failed because an asset-generation test depended on untracked runtime state or an audible TTS fallback.
Operations	Plans, benchmark harnesses, runbooks, alerts, and a Grafana dashboard exist. docs/load-test-signoff.md explicitly says execution evidence is pending.	"Operational planning artifacts exist."	"Load-tested," "cloud-ready," "operationally signed off," or "scalable."
Enterprise controls	No checked-in CI definition, Maven wrapper, container/deployment manifest, OpenAPI document, architecture-boundary gate, Testcontainers setup, SBOM/signing gate, Spring Security dependency, or threat model was found in Phase 1.	List each as a current gap.	"Secure," "Fortune 500 reference architecture," "cloud-native," or "release governed."
Licensing	Asset lookup can copy adjacent .license.txt files, but the repository has no complete model/asset/license inventory.	"Supports an adjacent license-file convention for selected assets."	"All assets/models are licensed" or "commercially usable."
Novelty	The repository combines known local analysis, planning, asset, and FFmpeg techniques around filesystem project contracts.	"Repository-specific integration candidate."	"Novel architecture," "research contribution," or "SOTA." No novelty search or external comparison is approved.

Plans and checked boxes prove intent or implementation bookkeeping only. They do not replace executed evidence. Generated files under target/, input/, output/, or local virtual environments are not certified evidence unless an evidence manifest names and hashes them.

Apply The Claim Ladder

Promote wording one level at a time. Never skip a level.

Level	Required support	Permitted verbs
0: Intended	Plan or prompt only	"plans," "targets," "proposes"
1: Implemented	Reviewed code at an immutable commit	"contains," "implements," "configures"
2: Tested	Deterministic automated test passes from a controlled checkout	"tests demonstrate," with scope
3: Measured	Retained representative artifacts and preregistered metrics pass	"measured," with numbers and uncertainty
4: Independently reproduced	Separate reviewer/environment recreates the result	"reproduced on ..."
5: Production qualified	Every applicable enterprise gate passes and operations approve	"production-qualified for [declared scope]"

Reject adjectives without a level and scope. Replace "fast" with throughput/latency under a named workload; replace "high quality" with rubric scores and confidence intervals; replace "secure" with the verified control set and unresolved risk count.

Gate High-Risk Claims

Build the evidence listed below before using the claim in a paper, release, presentation, or README. A result can satisfy one row without satisfying another.

Claim	Minimum evidence package
Production-ready output	Immutable source rights; no placeholder assets; model/asset provenance; approved director plan; measured media QA; blinded human review; failure/recovery results; retained final, manifest, logs, config, and checksums.
Cinematic quality	Preregistered category-balanced dataset; baseline outputs; randomized blinded review by declared reviewers; shot relevance, narrative coherence, pacing, visual finish, speech intelligibility, music/SFX fit, mix quality, and overall preference metrics; inter-rater agreement; confidence intervals; failure examples; technical QA.
Local models in runtime	Image/package inventory; exact model IDs, weight hashes, licenses, paths, memory/accelerator needs; startup/run traces showing local processes; egress-denied success; no host-only fallback; no runtime installation or model resolution.
Offline	Clean environment with network namespace/egress deny; preloaded approved bundle; packet/connection evidence; cold-start plus full source-to-final run; proof that caches were not inherited; failure if an undeclared artifact is removed.
Licensed assets	Source, owner, SPDX or verbatim license, commercial/derivative rights, territory/expiry if applicable, file hash, attribution obligation, and approval for every source, font, LUT, music, SFX, voice, model code, and weight. Generated output also requires model/weight/output-use analysis.
Secure	Threat model; authentication/authorization tests; OWASP ASVS 5.0 scope and evidence; secret/static/dependency/container scans; zero unresolved critical/high findings or recorded risk acceptance; least-privilege runtime; data/log redaction; audit evidence; secured actuator surface.
Scalable	Documented representative workload and hardware; p50/p95/p99, throughput, error rate, CPU, memory, GC, disk, threads, pools, queue age, and model saturation; 60-minute endurance; 2x peak; slowed-dependency test; horizontal-scale evidence; bottleneck and capacity limits. Do not inherit the user's example API numbers without adapting them to media workloads.
Reproducible	Clean checkout; one documented command; locked Java/Maven/Python/native/model inputs; checksums; no network for model/media work; macOS and Linux/VPS runs; one platform-neutral application artifact plus signed target-specific runtime/model/image bundles promoted without rebuild; deterministic seeds where applicable; declared numeric/media tolerance; independent reproduction.
SOTA	Approved primary-source review with dated search protocol; strongest relevant public baseline reproduced or obtained from auditable artifacts; same rights-cleared dataset and budget; preregistered metrics; uncertainty/significance; ablations; negative results; external review.
Fortune 500 reference architecture	Entire definition of done passes. Score all 15 human-review categories 0-4 with concrete evidence: architecture, domain, maintainability, security, testing, API, data, resilience, observability, performance, cloud operation, CI/CD, developer experience, documentation, and operations. No score below 3; average at least 3.5; security, data, testing, and operations each at least 3.

For the Fortune 500 claim, also require clean build/run, architecture gates, API contract, database migration from empty PostgreSQL, logs/metrics/traces/health/dashboards, load and resilience results, secure container evidence, deployment and rollback exercises, ADRs, and zero critical behavior dependent on undocumented assumptions.

Build A Defensible Cinematic Comparison

Do not choose only flattering footage. Freeze the evaluation before rendering.

1. Define intended users, distribution format, input constraints, output duration, content categories, hardware budget, latency budget, and prohibited content.
2. Create a rights-cleared, immutable, checksum-indexed dataset covering family, food, car, generic, low light, sparse events, noisy audio, no audio, long takes, and failure cases.
3. Freeze these internal baselines where applicable:
   • Source excerpt or uniform-window selection: measures whether highlight identification adds value.
   • Heuristic visual provider: measures the local CV model's contribution.
   • Deterministic plan: measures the director's contribution.
   • Source-audio-only render: measures generated or licensed audio assets.
   • Historical 5d889b0 ("working version but not cinematic"): use only after its runtime and exact outputs are reproducibly reconstructed.
4. Add an external baseline only after approved primary evidence and artifacts are vendored or cited. Network access is prohibited during this workflow; do not rely on memory for current products, versions, papers, benchmarks, or licenses.
5. Match source clips, output duration, compute budget, allowed assets, and human-review process.
6. Preregister metrics, thresholds, exclusions, stopping rule, statistical method, and all hypotheses. Predict expected numbers before execution under video-editing-research-methodology.
7. Randomize and blind human review. Hide system names, filenames, and render order. Retain raw scores and rejected samples.
8. Run ablations: remove local CV, director, generated music, SFX, voiceover, and each visual treatment separately. Require one mechanism to explain positive and negative observations.
9. Report distributions and confidence intervals, not only averages or a montage of best cases.
10. Send the result through video-editing-validation-and-qa, then change control, before promotion.

No cinematic acceptance threshold is currently agreed or evidenced. Keep the claim at "candidate" until the campaign establishes thresholds and passes them.

Record Artifact, Model, And License Provenance

Create one immutable manifest per evidence package. Store it in the approved evidence location defined by change control; do not silently add repository paths from this skill.

claim_id: <stable-id>
claim_text: <bounded proposed wording>
claim_level: <0-5>
commit: <40-character-sha>
created_utc: <timestamp>
owner: <team-or-role>
independent_reviewer: <team-or-role>
environments:
  - os: <macOS-or-Linux-distribution-and-version>
    architecture: <arm64-or-amd64>
    cpu: <model-and-count>
    memory_bytes: <integer>
    accelerator: <model-driver-runtime-or-none>
commands:
  - <exact-command>
network_policy: <egress-denied-evidence-reference>
inputs:
  - path: <logical-artifact-name>
    sha256: <hex>
    source: <approved-origin>
    license: <SPDX-or-verbatim-reference>
models:
  - id: <model-and-revision>
    weights_sha256: <hex>
    code_license: <reference>
    weights_license: <reference>
    output_use_review: <approval-reference>
outputs:
  - path: <logical-artifact-name>
    sha256: <hex>
metrics: <raw-and-summary-result-reference>
negative_results: <retained-result-reference>
limitations: <known-boundaries>
decision: <rejected-candidate-or-approved>

Reject provenance that says only "local," "open source," "free," or a mutable model alias. A cache hit is not proof that a model is bundled, approved, or available on a clean machine.

Prove Cross-Environment Reproducibility

Use the same immutable application and model/asset bundle in all environments.

Environment	Required proof
macOS development	Clean checkout; documented toolchain; no IDE dependency; egress denied; cold cache; source-to-final workflow; test and artifact logs. Record Apple/Intel architecture.
Linux/VPS production	Non-root runtime; explicit CPU/RAM/GPU/disk; egress denied; read-only filesystem except declared work volumes; signal/shutdown behavior; cold start; repeated render; recovery after restart.
Cloud	Same release artifact; externalized configuration/secrets; least privilege; readiness/liveness; resource limits; telemetry; rolling deploy and rollback; dependency outage and scale tests; no environment rebuild.

Define reproducibility tolerance before execution. For media output, compare timeline decisions, streams/codecs, duration, frames or perceptual hashes, loudness, clipping/silence, and human scores as appropriate. Never promise byte identity across FFmpeg, codec, CPU, or accelerator variants without proving it.

Review Every Claim

Copy this checklist into the claim review:

• Quote the exact proposed sentence and intended audience.
• Bound the workflow, environment, content categories, commit, and date.
• Assign a claim-ladder level and an evidence owner.
• Separate repository facts, measurements, interpretations, and candidates.
• Name the fairest baseline and equalize inputs, compute, time, and rights.
• Preregister metrics, thresholds, hypotheses, exclusions, and stopping rules.
• Attach exact commands, raw logs, configs, immutable inputs/outputs, and SHA-256 hashes.
• Inventory every dependency, binary, model, weight, font, LUT, source, music, SFX, and voice license.
• Prove no automatic download, external service, network access, placeholder, or unapproved render occurred.
• Include negative results, known failure cases, uncertainty, and scope limits.
• Reproduce on every environment named by the claim.
• Obtain independent factual, security/license, validation, and change-control approval.
• Make release wording no stronger than the weakest required evidence item.

Reject the claim if any required box is unknown. "Unknown" is a result, not permission to infer.

Write Release Notes Without Oversell

Use this template:

## <Release or experiment name>

Revision: `<commit>`
Status: <experimental | candidate | qualified for bounded scope>

### Changed
- <observable behavior, not aspiration>

### Verified
- <command, environment, dataset, measured result, threshold, evidence ID>

### Not verified
- <production, security, scale, offline, license, quality, or platform gaps>

### Models and assets
- <immutable IDs/hashes, licenses, approval, whether bundled>

### Compatibility and operations
- <configuration/API/data change, rollout, observability, rollback>

### Negative results and limitations
- <failures, excluded cases, uncertainty, known weak points>

### Claim decision
- Proposed wording: <exact sentence>
- Evidence level: <0-5>
- Reviewers: <roles>
- Decision: <rejected | candidate | approved for exact scope>

Do not describe a plan, prompt, unchecked runtime path, synthetic fixture, or mocked test as an end-user result. Link a release to retained evidence, not to a moving working directory.

Route Claim Promotion

1. Open the candidate under video-editing-research-methodology when the claim depends on a quality, novelty, mechanism, or comparative result.
2. Classify the implementation and any production-default impact under video-editing-change-control. Never change defaults to make an evaluation pass.
3. Generate the complete evidence package without network access or prohibited fallbacks.
4. Ask video-editing-validation-and-qa for threshold and evidence review.
5. Assign an adversarial reviewer to reproduce the result and seek counterexamples.
6. Run security/license review for any public, customer, or commercial use.
7. Approve only the exact bounded wording. Record rejected wording and the reason.
8. Publish limitations and negative results beside the claim.
9. Reopen the claim when dependencies, models, datasets, runtime environments, defaults, or relevant external baselines change.

Provenance and maintenance

This skill was grounded on repository revision 97ba827d507292e38387c188a4b88157fd119ddb and the project owner's criteria on 2026-07-21. Primary repository evidence included pom.xml, src/main/resources/application.yml, local worker scripts, editing/rendering code, tests, operational documents, highlight plans/checklists, and Git history. No network research was performed; current external SOTA, version support, vulnerabilities, and licenses remain unverified.

Re-verify volatile facts before every claim review:

git rev-parse HEAD
sed -n '1,260p' pom.xml
sed -n '1,180p' src/main/resources/application.yml
rg -n "pip install|get_pretrained|write_silence|fallback_tone|fallbackTone|writeSilence" tools src/main/java/org/example/videoclips/editing
rg -n "buildQaReport|new RenderQaCheck" src/main/java/org/example/videoclips/editing
find . -maxdepth 3 -type f \( -name 'mvnw*' -o -iname '*docker*' -o -iname '*compose*' -o -iname '*openapi*' -o -iname '*sbom*' \) -print
find . -maxdepth 3 -type f \( -path './.github/*' -o -name '.gitlab-ci.yml' -o -name 'Jenkinsfile' \) -print
rg -n "spring-security|SecurityFilterChain|ArchUnit|Modulith|Testcontainers|CycloneDX|dependency-check|OpenTelemetry" pom.xml src
sed -n '120,190p' docs/load-test-signoff.md
git log --oneline --all --decorate -80

Run build, media, security, load, offline, and cross-platform commands only through their sibling runbooks. Retain their logs and hashes; a command printed here is not evidence that it passed.