---
name: software-development-workflows
description: "Umbrella for planning, spikes, TDD, systematic debugging, code review requests, and language/runtime debugging workflows."
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [software-development, planning, spikes, tdd, debugging, code-review, workflows]
---

# Software Development Workflows

## Absorbed workflow classes

Former narrow software-development skills have been merged here so a maintainer can load one class-level workflow and then jump to labeled subsections/reference files:

- **Strict TDD / RED-GREEN-REFACTOR:** use `references/absorbed-test-driven-development.md` for the original full rules and `references/absorbed-test-driven-development-references-deterministic-demo-fixtures.md` plus `references/absorbed-test-driven-development-references-side-effect-free-delivery-boundaries.md` for detailed boundary patterns.
- **Parallel simplify/code cleanup:** use `references/absorbed-simplify-code.md` for the 3-reviewer delegation pattern covering reuse, quality, and efficiency.
- **Exploratory web-app QA / dogfooding:** use `references/absorbed-dogfood.md`, `references/absorbed-dogfood-references-issue-taxonomy.md`, and `references/absorbed-dogfood-templates-dogfood-report-template.md` for browser-driven bug finding and report format.
- **Statistical longitudinal/time-series code review:** use `references/statistical-time-series-code-review.md` for end-to-end missingness, explicit-zero, composite-target, lag/phase, event-semantics, Spearman/ties/dependence, BH, lab-quality, derived-platform-quality, and aggregate-only persistence checks with deterministic counterexample probes.
- **Time-series cockpit contract/chart audit:** use `references/time-series-cockpit-contract-chart-audit.md` for provider→contract→Chart.js tracing, strict point-quality and baseline invariants, dense calendar gaps, derived measurement-age/delta/coverage cards, deterministic main-trend fallback, separate aligned event lanes, browser assertions, and concurrent-worktree rechecks.
- **Vue/PrimeVue dashboard migration:** use `references/absorbed-vue-primevue-dashboard-migration.md` plus the prefixed Vue migration references for PrimeVue/Aura shell migration, light-theme contrast, creator dashboards, mock command dashboards, YouTube CSV analytics, and gateway/Vue hardening.

Reference note: for FamilyDashboard Home/Todo moving status timelines, use `references/familydashboard-moving-timeline.md`.

Reference note: for independent medical-safety, privacy, and code-quality reviews of health correlation engines, symptom CLIs, dashboards, and persisted analytics, use `references/health-analytics-safety-privacy-code-review.md`. It requires end-to-end tracing of legacy writers and displayed outputs, missing-as-unknown checks at every boundary, allowlisted lab identifiers, freshness/invalidation review, synthetic runtime/schema verification, and exact Important findings rather than approval based only on green tests. For offline health reconciliation tools that combine read-only source audits, private detailed artifacts, aggregate versioned evidence, original-document probes, and optional exact-link migrations, also use `references/read-only-health-reconciliation-security-review.md`; it adds symlink/mode/repository-containment probes, duplicate URL/query checks, reviewed-original gate tracing, pre-commit migration postconditions, trigger counterexamples, and real restore-test semantics. For final dashboard release probes covering medication plan identity/status boundaries, contract-level lab spoofing, browser-enforced synthetic-only execution, and print disclaimer completeness, pair it with `references/health-dashboard-final-review-addendum.md`. For final exact-tree approval after late fixes, also use `references/exact-tree-health-dashboard-release-review.md`: it adds untracked-file scanning, byte-deterministic fixture/HTML checksums, changed-file lint versus disclosed legacy baseline debt, frozen-v4/shared-surface verification, and a controlled isolated-port browser gate that cannot accidentally validate a stale or foreign server.

Reference note: for source-only audits before adding sensitive read-only HTTP APIs, use `references/read-only-sensitive-http-api-pattern-audit.md`. It traces authentication versus CSRF/loopback, Host/Origin, route-specific CSP, `no-store` on error paths, strict scalar query parsing, SQL-level row/range limits, exact route/path allowlists, explicit read-only DB targeting, registry-driven search, synthetic marked fixtures, and an unchanged-tree verification/reporting shape.

Reference note: for read-only nutrition-day audits spanning a summary day endpoint, detailed meals/products/macros/nutrients, stale/abort-safe day rendering, and an opaque mapping queue/deep-link workflow, use `references/nutrition-day-contract-ui-queue-audit.md`. It adds structural no-PHI payload reporting, exact key+unit allowlists, server-derived unique queue identity, future-policy reconciliation, unknown-meal normalization, and unit/browser verification for out-of-order requests and mapping navigation. When the backend must also compare intake with age/sex/factor-specific public-health nutrient references, pair it with `references/nutrition-reference-contract-profile-audit.md`: local immutable source data, explicit versioned profiles, no-default group resolution, per-nutrient documented-day denominators, per-food missingness, unclamped point/range percentages, source/group/as-of provenance, and neutral non-diagnostic output.

Reference note: for a feature-flagged, read-only Health record slice with document search, FTS, originals, and browser routing, use `references/health-dashboard-record-workflow-hardening.md`. It requires SQL-before-limit pagination with opaque cursors, current review-status FTS joins and literal token quoting, one shared chunk contract, descriptor-based original streaming, central-router direct-link/history behavior, text-node-only data rendering, and flow-specific synthetic browser evidence before a release claim. When an authenticated review inbox must expose pending originals or extracted previews while keeping FTS, reports, and medical summaries reviewed-only, also use `references/document-review-preview-security-boundary.md`; it separates technical availability from trust, preserves reviewed-policy wrappers for reconciliation, checks nested report overviews and legacy numeric routes, and adds pending-document TOCTOU/no-leak attack probes.

Reference note: for an integration gate that adds a browser session to a sensitive token-protected API without changing the dashboard UI, use `references/sensitive-dashboard-api-integration-gate.md`. It covers separate server-side browser bootstrap credentials, short-lived HttpOnly SameSite cookies, V5-only `connect-src 'self'`, metric-specific weekly contracts, non-auto-releasing identifier inventory reports, synthetic browser proof, and a versioned final test protocol. For the authorization-versus-CSRF boundary and page-to-session proof, also use `references/browser-session-authentication-boundary.md`. For a bounded read-only ECharts/API Explorer slice, use `references/health-dashboard-read-api-explorer-release.md`: contract-first time-series fields, endpoint disclosure separation, no-token browser bootstrap, accessible fallback, fixture isolation, and release gates.

Reference note: for private health-dashboard write paths where the HTTP process must never mutate the health DB directly, use `references/private-health-dashboard-capture-queue.md`. It covers exact form/CSRF/origin validation, bounded atomic `0700`/`0600` queues, no-follow worker revalidation, explicit DB targeting, local-timezone capture dates independent of stale bundles, truthful one-time queued receipts including HEAD/replay handling, mobile dialog accessibility, private image quarantine with decode/re-encode/metadata stripping and SHA-256 dedupe, append-only correction/withdrawal versions, copy-first DB-plus-media release gates, synthetic end-to-end verification, and real-data read-only private smokes.

Reference note: for browser-backed dashboard UX/accessibility release reviews with an `APPROVED only if no Important/Critical issue` gate, use `references/dashboard-ux-accessibility-release-review.md`. It covers exact viewport probes, all-view mutual exclusion, real period-series changes, lazy chart lifecycle, 44px target measurement, keyboard/ARIA state, privacy and print computed-style checks, long labels, schema-only empty states, synthetic-only runtime evidence, test-gap analysis, and separate non-blocking sprint deferrals.

Reference note: when long sensitive review queues or document timelines must become desktop/mobile master-detail workspaces without changing trust or worker semantics, use `references/dashboard-review-master-detail-navigation.md`. It covers one-form-at-a-time review details, combined document status lines, collapsed technical provenance, canonical filter/sort/selection URL state, mobile list/detail back and focus, `<details>`-independent history restoration, subview-owned range headers, bounded-filter honesty, targeted historical regression migration, incidental screenshot cleanup, and focused release gates.

Reference note: for read-only desktop-first health-dashboard UX/code audits and redesign blueprints, use `references/desktop-first-health-dashboard-ux-code-audit.md`. It adds rendered-structure-versus-dormant-CSS checks, computed cascade/navigation evidence, fixed-navigation occlusion probes, future-observation exclusion, exact-contract revision risks, desktop/tablet/mobile shell breakpoints, and synthetic-only cleanup/reverification discipline. Pair it with `references/time-series-cockpit-contract-chart-audit.md` when the audit reaches provider/contract/chart semantics.

Reference note: for frontend-only polish and bounded private releases across nutrition, food mapping, record, document review, FullCalendar, and mobile capture while schemas/APIs/medical semantics stay frozen, use `references/private-health-dashboard-ui-polish-release.md`. It covers honest missing/reference display, master-detail separation, neutral same-unit lab deltas, mobile `listMonth`, fixed-launcher containing-block/cascade diagnostics, exact capped browser scenarios, compact security/medical diffs, atomic private deployment, and a read-only smoke that distinguishes real request failures from navigation aborts.

Reference note: when a sensitive dashboard action returns 403 or a visible Today/task button no longer opens its dialog, use `references/health-dashboard-origin-csrf-dialog-regression-audit.md`. It separates exact public-Origin failures from one-time-CSRF failures with disposable browser probes, preserves every security boundary, detects dead proxy-trigger selectors that also disable focus/close behavior, distinguishes queue-file idempotency from request idempotency, and defines HTTP/HTTPS/inline-error/dialog regression matrices.

Reference note: for bounded advanced Explorer shells where backend contracts and statistics are frozen, use `references/bounded-advanced-explorer-frontend-shell.md`. It covers bundle-only raw/baseline modes, compatible-unit and series caps, deterministic presets and fixtures, shared selection gating across every result surface, honest aggregate-scope disclosure, cadence-aligned event lanes, all-null empty states, Chart.js internal-vs-CSS geometry at 200% text, chart destruction/reuse, accessible controls, responsive/print behavior, and explicit separation of browser evidence from unit/syntax checks.

Reference note: when a dashboard has accumulated competing Chart.js/ECharts explorers and bundle/API/custom period controls, use `references/single-explorer-central-url-range-contract.md`. It traces ownership and hidden control coupling, selects one production explorer, defines a canonical preset/custom URL contract, preserves range state across day/record routers, treats chart zoom separately from data scope, and verifies backend limits before promising “all.”

Reference note: for synthetic-only browser acceptance and feature-flagged visualization spikes, use `references/synthetic-browser-acceptance-plan-audit.md`. Its visualization-spike section adds fixed/private sandbox roots, fixture markers, same-connection read-only DB binding, exclusive no-replace output, real tooltip/pan/brush/drill-down probes, 200%/print geometry, five-run performance gates, one combined browser command, complete vendored license/NOTICE/subcomponent closure, and exact-tree re-review after concurrent fixes.

Reference note: for FamilyDashboard departure warning sounds, daily math quiz, per-child quiz difficulty settings, and admin tab organization, use `references/familydashboard-sound-math-admin-quiz.md`.

Reference note: for FamilyDashboard task-template row layout, and calendar event edit/delete/drag-drop patterns, use `references/familydashboard-admin-quiz-calendar.md`.

Reference note: for FamilyDashboard shared daily bonus-task semantics — one completion per day across both children, sibling undo reopening both instances, exactly-one ledger booking, and Admin add-task layout overlap fixes — use `references/familydashboard-shared-daily-bonus-tasks.md`.

Reference note: for FamilyDashboard task-template deactivation/soft-delete, cancelling open current/future instances, dashboard visibility filtering, inactive-template day-close penalties, and Timeline-replaced tasks such as Zähneputzen, use `references/familydashboard-task-template-deactivation.md`.

Reference note: for FamilyDashboard Admin Aufgaben & Coins action semantics (Deaktivieren vs Löschen), tombstone markers to prevent seed recreation, Coin-Guthaben full-width card layout, and iPad admin UI smokes, use `references/familydashboard-admin-task-actions-layout.md`.

Reference note: for FamilyDashboard selected-day/full-day timeline milestone cleanup, Gutenachtritual/sleep anchoring, quiz/math coin refresh, append-only Admin coin voids, and stale calendar edit dialogs, use `references/familydashboard-timeline-coins-calendar-hardening.md`.

Reference note: for FamilyDashboard Challenges/Geografie-Quiz, local SVG Switzerland map MVP, ChallengePoints, weekly Gasser-Coin conversion, and calendar soft-delete hardening, use `references/familydashboard-challenges-calendar-delete.md`.

Reference note: for FamilyDashboard `Allgemeinwissen des Tages`, stable daily quiz snapshots, configurable knowledge quiz coins/levels, Swiss primary math prompt wording (`X : 2` not `1/2 von X`), and school-start marker vertical polish, use `references/familydashboard-daily-knowledge-quiz.md`.

Reference note: for FamilyDashboard Bildschirmzeit/Screen Time, child-started timers, same-day Shop exchanges (`4 Coins = +10 minutes` configurable), selectable alarm sounds, and Admin day/week allowance controls, use `references/familydashboard-screen-time-shop.md`.

Reference note: for FamilyDashboard morning `Loslaufen in ...` countdown regressions where the status card displays a later lunch/afternoon departure instead of the immediate schoolway, use `references/familydashboard-morning-departure-countdown.md`.

Reference note: for FamilyDashboard two-phase morning routine countdowns (`Zähneputzen in ...` before `Loslaufen in ...`) plus Admin Stundenplan day-header detail editing for per-child/day teeth-start/timer-hooks, use `references/familydashboard-routine-countdown-admin.md`.

Reference note: for FamilyDashboard Bildschirmzeit features — countdown timers, 40-minute default allowances, Shop exchanges, earned screen-time tasks, Admin rule management, weekly parent reports, sidebar rest-time badges, JS timestamp pitfalls, and stop-duration persistence — use `references/familydashboard-screen-time.md`.

Reference note: for creator-facing dashboard polish in German, use `references/creator-facing-dashboard-german-ux-polish.md`.

Reference note: for read-only audits of static-web build/test/performance setup, temporary reproducible builds, minimal Playwright/Lighthouse gates, concurrent-worktree handling, and safe animation/3D dependency removal, use `references/read-only-static-web-performance-audit.md`.

Use this class-level skill when the user asks for a development method rather than a tool-specific integration: plan before building, run a spike, use TDD, debug systematically, request a pre-commit review, or attach a language/runtime debugger.

## Pick the mode

- **Plan mode** — write an implementation plan to `.hermes/plans/` and do not execute code until the user asks.
- **Writing plans** — produce bite-sized tasks with exact files, tests, and acceptance criteria.
- **Spike** — build a throwaway experiment to validate feasibility before committing to an implementation.
- **TDD** — enforce RED → GREEN → REFACTOR; write a failing test before the fix when practical.
- **Systematic debugging** — reproduce, localize, hypothesize, minimally fix, then verify.
- **Requesting code review** — run pre-commit quality/security gates and summarize risks before opening/merging.
- **Python / Node debugger** — attach `debugpy`, `pdb`, or Node `--inspect` only when normal logs/tests are insufficient.

## General rules

1. Inspect current repo state before edits.
2. Identify the smallest verification command that proves the requested behavior.
3. Prefer narrow, reversible changes.
4. Do not stop at a stub, plan, or progress/status message when the user asked to build/verify through a defined end state. Keep tool execution continuous in the same assignment until verified completion or the user's explicit blocker threshold; a progress message must be followed by more tool work, not a final answer.
5. Before declaring completion, consume every dispatched review/delegation result. When implementation and independent review overlap, late findings are release gates: correct overclaims, harden critical gaps, rerun verification, and version/archive incompatible evidence before reporting final status.
6. Separate exploratory spike artifacts from production code unless the user asks to promote them.
6. For greenfield product repositories, use `references/greenfield-fullstack-mvp-bootstrap.md`: combine RED tests, real backend primitives, a usable frontend path, devops/docs, smoke tests, and a remote-backed commit in the first delivery.
7. For Google Drive/Docs blueprint-driven local dashboard/PWA/app builds, use `references/drive-blueprint-greenfield-dashboard-bootstrap.md`: archive the blueprint locally and in `docs/`, extract phases/acceptance criteria first, implement strictly one phase/auftrag at a time, document target-device CSS viewport assumptions before UI work, add Docker setup notes when Compose is part of acceptance, and report Docker/GitHub blockers separately from verified local test/build evidence.
For local family dashboards with task completion, children’s points/coins, benefits, or day-close penalties, use `references/local-family-dashboard-task-ledger.md`: immutable ledger-derived balances, idempotent child-tap actions, lazy past-day finalization, and penalty reversal rather than deleting history. For child-facing coin explainability and admin correction bookings, use `references/familydashboard-coin-ledger-corrections.md`: read-only `/coins` ledger page, clickable sidebar coin indicator, append-only manual correction transactions with required comments, optional reference transaction IDs, and no direct balance edits. For Admin manual coin booking regressions, `+10` booking deltas, bulk void/delete/reset maintenance, and baseline-aware ledger tests, use `references/familydashboard-admin-coin-management-regression.md`. For configurable quiz rewards, Rechnung-des-Tages/Sprach-Challenge coins, calendar event edit/delete/drag, and Admin layout polish, use `references/familydashboard-quiz-rewards-calendar-editing.md`: AppSetting-driven quiz coin values, idempotent reward transactions, no old ledger edits, editable informative calendar event edits, and iPad-safe admin action rows. For the follow-on calendar/exams phase, use `references/local-family-dashboard-calendar-exams.md`: 3-week day-bucket calendar API, minimal Exam admin endpoints, backward study-plan generation, study tasks on Home/Todo, cancellation semantics, and focused verification. For integrated weekly school timetables, use `references/local-family-dashboard-schedule.md`: structured time slots/day/block models, read-only child grid, PIN-protected touch admin editor, school start/end/leave-time/timeline integration, overlap warnings, and reference-photo seed notes without OCR as a runtime feature. For child status cards and lunch/school/free timeline polish, use `references/local-family-dashboard-status-timeline.md`: iPad-legible countdown cards, proportional moving time bars, no stale `Schulbeginn` hints while school is running, and short labels under the bar. For FamilyDashboard DB persistence/admin-data protection, use `references/familydashboard-persistence-guardrails.md`: production DB bind-mount invariants, backups before changes, test DB isolation, seed/reset guardrails, and rebuild persistence checks. For the late PWA/stabilization phase, use `references/local-dashboard-pwa-backup-stabilization.md`: iPad PWA shell, Playwright smoke, SQLite Docker backup/restore, container tests, request logging, and persistence verification. For post-iPad user feedback polish, use `references/local-family-dashboard-ipad-feedback-polish.md`: morning routine progress-bar timelines, stable task rows that prevent Bonus jumping, existing-DB admin PIN reseeding, and honest temporary Tailnet preview handling when final Docker gates are blocked.
8. For fullstack dashboard previews over a Tailnet, use `references/tailnet-dev-dashboard-preview.md`: prefer Tailscale Serve when permitted; otherwise bind the frontend to `0.0.0.0`, keep the backend localhost/internal, proxy `/api` server-side, and verify the Tailnet-IP link plus browser console. For dashboard control planes above specialist trading/executor bots, use `references/financemanager-cryptotrader-approval-bridge.md`: read runtime state only, synthesize TradeIntent rows, write approval/audit decisions only, and keep actual execution inside the trader after separate gate checks. For Streamlit/Python tools that must become iPhone/iPad-usable internal web apps over Tailscale with local voice-note/video uploads, use `references/mobile-tailnet-streamlit-webapp.md`: bind Streamlit to `0.0.0.0`, include iOS formats like `.m4a` and `.mov`, add mobile CSS/touch polish, run as a user systemd service, and verify both localhost and Tailnet HTTP 200. For such tools that need best-quality local meeting-recording transcription without slowing Hermes/Telegram voice clips, use `references/gpu-local-stt-meeting-recordings.md`: keep domain-tool STT separate, run WhisperX/faster-whisper `large-v3` on CUDA with VRAM logging, try parallel operation with resident TTS services first, and add `int8_float16` OOM fallback before asking to stop other GPU services. For AutoProtocol/Streamlit services that call CodexCLI after STT, use `references/autoprotocol-streamlit-codex-service-hardening.md`: account for minimal systemd user-service PATHs, resolve CodexCLI via `CODEX_BIN`/known install paths, pass a safe subprocess PATH, and save the raw transcript before the LLM protocol step so expensive STT output is not lost. If a Streamlit restart lost the UI session but uploaded media remains in `input/`, use `references/autoprotocol-manual-recovery-rerun.md`: inspect existing uploads first, rerun the same production pipeline from a tracked background CLI process, preserve raw transcript before LLM, and deliver only verified `.docx` artefacts/paths. For multi-dashboard operator handoffs where existing dashboards must be started together and fixed ports must be preserved, use `references/tailnet-multi-dashboard-handoff.md`: override conflicting defaults, keep explicitly fixed ports unchanged, serve built `dist/` copies with a temporary Python static/proxy server when Node/Vite is unavailable, and report only verified Tailnet URLs. If a Tailnet dashboard opens but shows no data, use `references/tailnet-dashboard-cors-readiness.md`: verify the backend data shape safely, then test CORS from the actual dynamic frontend origin before changing UI code; add/maintain `make handoff-status` style checks for URL reachability, CORS, DB/source readiness, and non-empty safe data shape.

9. For the inventory/review phase of such command dashboards, use `references/command-dashboard-inventory-phase.md`: create docs only, inspect code/routes/start scripts without opening productive DBs/reports/exports/secrets, classify integrations Green/Yellow/Red with reasons, enforce iPad/minimal-start-page constraints, and verify no sensitive files or secret patterns were added before commit/push.
10. Before bootstrapping code in a sensitive command-dashboard repo, use `references/command-dashboard-repository-safety-bootstrap.md`: add conservative `.gitignore`, placeholder-only `.env.example`, README, Makefile, stdlib safety scanner, repo-safety docs/runbook/ADR, validate JSON examples, scan forbidden fields/secrets/runtime leaks, then commit/push only after `make verify` passes.
11. Before building the first real UI or domain adapters for a sensitive command dashboard, use `references/command-dashboard-mock-gateway-hardening.md`: fix contract drift across docs/Pydantic/schemas/OpenAPI/fixtures, enforce fixture sync and response safety tests, add local-dev CORS only for explicit origins, export/check OpenAPI, and write a concrete iPad-first UX blueprint before frontend code.
11. For local E2E/visual QA of a mock-only sensitive command dashboard, use `references/command-dashboard-local-e2e-visual-smoke.md`: keep browser/server E2E separate from fast `make verify`, dynamically choose local ports without killing foreign processes, run Playwright against the real mock Gateway + Dashboard, validate desktop/iPad/offline/safety behavior, and keep screenshots/reports in ignored artefact folders.
12. For the UX acceptance/detail-polish phase of a mock-only sensitive command dashboard, use `references/command-dashboard-ux-acceptance-detail-polish.md`: extract shared read-only module-detail components, add safe module routes for first-class cards such as AutoShorts, validate Home/detail/iPad/Desktop/accessibility-light rules with Playwright, keep browser E2E out of fast `make verify`, and watch for safety-copy/test pitfalls like forbidden words in explanatory text, Vite dev HTML paths, async locator counts, and iPad `lg` breakpoint collisions.
13. For the first real read-only domain integration behind a sensitive command dashboard, use `references/command-dashboard-readonly-domain-adapter.md`: keep `mock` as default, add `live_readonly`/`disabled` adapter modes, write sanitizer/mode/resilience tests first, allowlist only derived summary fields into the existing `ModuleSnapshot` contract, convert live failures into degraded snapshots, keep other modules mock, and add optional local live smoke outside `make verify`.
14. When validating that read-only adapter against a genuinely local live backend, use `references/command-dashboard-live-readonly-contract-smoke.md`: discover/start only localhost services from read-only metadata, probe approved GET endpoint shapes structurally without committing raw responses, run the gateway live smoke, harden allowlist sanitizers from real shapes, add synthetic live-shape/dirty fixtures, document a redacted contract review, stop started processes, and keep live smoke outside fast `make verify`. For AutoShorts/creator-production style dashboards, also see `references/autoshorts-live-readonly-smoke.md`: start backend-only with temp ignored DB/storage roots, probe only GET `/api/health` and safe summary endpoints structurally, ignore nested package/topic objects, and never mark freshness as `fresh` unless the backend exposes an explicit safe freshness signal.
15. For ultra-sensitive domains such as Health where even read-only live data is too risky, use `references/command-dashboard-ultrasensitive-metadata-probe.md`: build a `mock|disabled|local_probe` metadata-only adapter first, inspect only code/docs and filesystem metadata (existence/count/mtime/size bucket/freshness), never read PDFs/DB rows/OCR/JSON/CSV/report/log content, keep paths/filenames out of API output and docs, use allowlist-only KPIs (pipeline status, freshness category, bounded review count), add dirty synthetic fixtures plus inventory/forbidden-surface tests, and keep optional local smoke outside `make verify`.
16. For safe marker bridges or production-status-only read-only adapters (Health markers, AutoShorts status snapshots, similar), use `references/command-dashboard-safe-status-marker-and-readonly-status.md`: keep default `mock`, validate strict marker schemas or allowlisted localhost GETs, map only enums/counts/categories into `ModuleSnapshot`, prove local probes do not open runtime files, and keep all marker paths/media filenames/scripts/prompts/tokens out of API output.
17. For an operator-facing local test/demo release of a sensitive command dashboard, use `references/command-dashboard-operator-demo-pack.md`: add `demo_mock` as the default no-runtime profile, optional localhost-only mixed read-only profile, `make demo`/`make demo-stop`/`make smoke-operator-demo` outside `make verify`, PID/logs only under ignored `.tmp/`, direct Vite/uvicorn `exec` process handling, a read-only banner/source badges, `/api/demo-info` if useful, and an operator runbook/checklist.
18. When the operator demo opens but feels too passive, use `references/command-dashboard-operator-handoff-links.md`: add runtime-configured legacy handoff links with a strict server-side validator, expose only configured/not_configured/blocked link status in APIs/settings, make `/approvals`, `/reports`, and `/settings` useful but read-only, and extend smoke coverage across all operator routes without adding actions/iframes/media/raw data. If user testing shows links remain `not_configured` and the dashboard still does not lead to real workspaces, escalate to `references/command-dashboard-real-operator-handoff.md`: start/detect existing local dashboards, set link URLs at runtime, verify Finance/AutoShorts (or analogous) dashboards are actually reachable, and leave the handoff running for the operator to test. If the links work but operators still find the UX confusing, use `references/command-dashboard-operator-ux-clarification.md`: remove redundant detail-page “Open module” buttons, clarify internal summary vs external specialist dashboards, represent intentionally locked sensitive domains as `locked_by_policy` plus safe workspace available, and strengthen smoke/tests around UX labels and no-action guarantees. If an existing FamilyDashboard should become a first-class bucket rather than a loose link, use `references/command-dashboard-family-bucket-and-operator-readiness.md`: add `family` to contracts/registry/overview, preserve FamilyDashboard port 5173, runtime-configure `FAMILY_LEGACY_DASHBOARD_URL`, branch external Vue links to `<a>` rather than `RouterLink`, and replace misleading visible “Demo mode” copy with operator/read-only wording. If the home page itself still feels like an admin directory rather than useful operational guidance, use `references/command-dashboard-home-ux-family-handoff.md`: promote Command Briefing + Ampelstatus above module cards, fix mobile viewport/navigation, and add FamilyDashboard handoff without stealing its fixed `5173` port.
19. For sensitive dashboards that need to display trader live-readiness above a separate executor, use `references/command-dashboard-readonly-trader-preflight.md`: add a read-only preflight endpoint/panel, derive conservative fail-closed gates from snapshots/scorecards when no bot export exists, force all execution flags false even if upstream data says otherwise, sanitize credential/path labels before safety guards, update OpenAPI/client/types/UI tests, and verify `contains_path=false` plus no live/signed action.
20. If an ultra-sensitive Health module is safe but medically useless because it only shows pipeline/backup/contract metadata, use `references/command-dashboard-health-risk-cockpit.md`: build a strict fixed-domain traffic-light risk cockpit, move technical metadata to a secondary/collapsed section, map Overview to risk KPIs rather than plumbing, open any existing Health dashboard only as `configured_protected` link-only handoff, and never parse/embed Health reports, PDFs, OCR, DB rows, raw labs, filenames, paths, or Drive IDs.
20. If a command-dashboard home page feels like an admin dashboard rather than a useful operator cockpit, use `references/command-dashboard-overview-ux-ampel-mobile.md`: lead with a single command briefing, add an Ampel/traffic-light layer before module-detail cards, keep sensitive modules summarized via safe KPIs only, and verify mobile viewport/nav behavior explicitly.
14. For creator/customer-facing dashboards sitting on internal automation, use `references/creator-facing-dashboard-product-framing.md`: hide internal agent/bot/AI production language from the visible UI, frame work as prepared packages/review/approval/topic planning, and verify frontend copy before reporting product readiness.
12. For creator/customer-facing dashboards sitting on internal automation, use `references/creator-facing-dashboard-product-framing.md`: hide internal agent/bot/AI production language from the visible UI, frame work as prepared packages/review/approval/topic planning, and verify frontend copy before reporting product readiness.
9. For prepared-video publishing dashboards, use `references/prepared-video-publishing-dashboard-sprint.md`: token hygiene first, then neutral language, operations cockpit, prepared-package import, review/approval page, topics/ideas database, seed data, and only then provider uploads.
10. For creator analytics/learning-loop dashboards, use `references/creator-analytics-learning-loop.md`: collapse analytics to Results / Improvements / Import data, make views visible by default, record CreativeChange + ActivityEvent, and connect changes to before/after snapshots without overclaiming statistical certainty.
11. For dashboards that control updates to a separate static website repo, use `references/dashboard-controlled-static-website-bridge.md`: model website companion state explicitly, prepare/generate/QA/show-diff before any push, resolve cross-repo media paths absolutely, and for analytics CSV recovery classify files by CSV header/content before falling back to filenames.
12. When real platform analytics are imported but unlinked from creator content, use `references/analytics-to-content-website-mapping.md`: build a source index across website candidates/markdown, upload audits, review packages, and dashboard objects; auto-link only unique high-confidence ID matches; surface family/script/package/website status and next recommendations.
13. For video dashboards with analytics-only rows, website-only companions, thumbnails, or a first private platform-upload flow, use `references/dashboard-media-path-and-private-upload.md`: guard media paths with non-empty `is_file()` checks before ffmpeg/FileResponse, add placeholder regressions, implement YouTube upload as private-only/audited/confirmed, and provide a dry-run path that exercises DB/audit/context updates without calling the provider.
14. For creator dashboards that add YouTube upload capability, use `references/youtube-private-upload-dashboard-mvp.md`: implement OAuth with `youtube.upload` scope, private-only upload jobs, encrypted tokens, dry-run IDs, upload audits, ID/context linking, and a strict no-automatic-website-push gate.
15. For concept-gated production dashboards, use `references/concept-gated-dashboard-production.md`: the dashboard queue is the source of truth; chat commands only trigger `GET /api/agent/production/next` + concept proposal, and production must not start until explicit `APPROVE_PRODUCTION <queue_item_id>` followed by `approve-generation`; legacy `send-to-production` routes must never directly set `producing`.
16. When a dashboard/control-plane must sit on top of an already-working external automation path, use `references/existing-executor-reconciliation-and-production-queue.md`: reconcile existing provider IDs/audits and cross-repo content before acting, model the proven executor explicitly, create token-free request/outbox or agent-polling APIs, import completion audits, expose a creator-controlled production queue with 10+ explainable recommendations, duplicate/rotation signals, concept-gated agent production, safe active-workspace reset, validate the agent→package→review→upload-request loop with a low-cost test package before any real upload/final render, and never attach imported packages by “last video ID” when scans can return multiple folders.

## Preserved source details

Full absorbed source skills are preserved in `references/absorbed-*.md` for complete step lists, prompts, and command examples.