Weekly development deck product specification

• Status: Proposed; merging the pull request that carries this document records approval of revision 1
• Owner: Weekly development report owner (@fmuia), with the development meeting
• Revision: 1 (2026-10-25)
• Architecture: ADR 0004
• Applies to: the final weekly development deck and its internal diagnostic draft; not a business report

This is the human-owned product contract for the weekly development deck. It defines what the meeting should learn and decide, how ClickUp and GitHub appear, what the required editorial model may do, and what a readable deck looks like. The editorial schema, prompt, composer and renderer implement this contract; they do not make these product decisions independently.

The words must, must not, required, may and should are normative. Examples in this document are schematic, not current ecosystem facts.

Implementation boundary

The current publication composer does not implement this specification, and current optional commentary remains insufficient. The required editorial artifact can be validated in a review-only shadow run, and an explicit feature-flagged composer can turn a valid artifact into an immutable internal preview; both receipts record no publication effect. A final deck may move to this contract only after the evidence, editorial and visual reviews pass.

Review the product choices first

Approval of this revision means accepting these six choices:

1. The deck is a decision aid for the weekly development meeting, not an exhaustive status presentation.
2. ClickUp's observed hierarchy provides the main organisation; GitHub remains authoritative for development execution facts and complete during the transition.
3. Model synthesis is required and integrated throughout the narrative. It is not a separate, optional commentary section.
4. The live narrative targets 12–18 slides and cannot exceed 24; complete evidence remains available in an appendix.
5. The visual system is pinned to the HSSM design specification and prioritises projection readability over fitting more text.
6. Material changes to these choices require a new owner-reviewed specification revision.

Audience, purpose and meeting promise

Audience

The primary audience is the HSSM development meeting: contributors, maintainers, project-management participants and the people who can resolve cross-repository decisions. Readers know their own work in detail but cannot be expected to know every repository, ClickUp branch or dependency.

The secondary audience is a maintainer revisiting the deck after the meeting. They must be able to trace its claims to the retained evidence and distinguish provider facts, editorial interpretation and meeting recommendations.

Purpose

The deck must turn one reporting window into shared situational awareness and a bounded forward agenda. By the end of the live narrative, the meeting should be able to answer:

• What materially changed, and why does it matter?
• Where does the work sit in the observed ClickUp structure?
• Which cross-area dependencies, risks or blockers need intervention?
• Which decisions are due, and what evidence bears on them?
• What should receive attention next, and who needs to participate?
• What development work is not yet represented in ClickUp?

The deck is not the system of record, a replacement for ClickUp, a pull-request browser, or a performance scorecard. Its claims are a dated reading of retained GitHub and ClickUp observations.

Evidence and hierarchy

Authority remains visible

• GitHub owns repository, issue, pull-request, review, check and release facts.
• ClickUp owns its hierarchy, ordering, task state, priority, assignment, dependency and ClickUp-only project-management work.
• Reconciliation owns only the explicit observed relationship and its state: mapped, unmapped, ambiguous, stale, excluded or ClickUp-only.
• The editorial model owns interpretation and recommendations, never provider state.

A ClickUp task may represent or aggregate GitHub records, but copied GitHub status in ClickUp must not replace a direct GitHub observation. The deck must not establish a relationship from title similarity or model inference.

Organise by the observed ClickUp structure

When a permitted ClickUp observation exists, the deck must preserve its actual ancestry and display order:

Workspace
└── Space
    ├── Folder
    │   └── Subfolder …
    │       └── List
    │           └── Task
    │               └── Subtask …
    └── List
        └── Task

The interface may call a level a thread, subthread, stream or milestone, but the deck must use the human-readable name observed in ClickUp and retain the full lineage in notes or the appendix. It must not assume a fixed number of threads, hard-code today's folder names, or read the Git-backed roadmap as a substitute hierarchy.

Every top-level in-scope ClickUp branch appears in the overview, including a branch with no material movement. Detailed live slides are selected by materiality; selection cannot erase the branch from the overview or evidence appendix.

Reconciliation states

State	Main narrative	Evidence appendix
Mapped	Place the GitHub work under its explicit ClickUp location; show GitHub-native state.	Record both identities and relationship provenance.
Unmapped GitHub	Show a visible coverage count. Give material unmapped work a labelled live callout or slide.	List every in-scope record under Not yet mapped in ClickUp.
Ambiguous	Do not attach it to any ClickUp branch. Show it as a relationship decision when material.	List every candidate relationship and provenance.
Stale	Label the relationship stale and unresolved. Do not use it to assign GitHub work to a current ClickUp branch; show material work as a coverage or relationship-decision item.	Retain every candidate identity, relationship provenance, source revision and stale reason.
Excluded	Do not use it as narrative evidence.	Record the reviewed exclusion and reason.
ClickUp-only	Place it in the observed hierarchy with a PM-only label. Never imply code movement.	Retain its ClickUp identity and state.

Relationship staleness is independent of provider-observation age. A stale relationship may join fresh observations and may retain several candidate locations; none establishes a current placement. Each provider's facts retain their own observation time and freshness label. A stale relationship must not replace current GitHub facts with an older reading or degrade unrelated mapped work to repository grouping.

Separately, during transition mode, an unavailable or permitted stale ClickUp observation may degrade organisation but must not reduce GitHub coverage. The deck must label the degraded state and use a plainly temporary GitHub repository grouping; any retained ClickUp reading is visibly dated and never presented as current. It must not silently revive the Git-backed roadmap. In ClickUp-complete mode, a missing or over-age ClickUp observation or any unmapped, ambiguous or stale reconciliation entry prevents final publication.

Narrative contract

Required sequence

The live narrative follows this arc. A section may take more than one slide, but changing the order is an editorial exception that must be recorded.

1. Cover. Reporting window, deck identity and no other claim.
2. Executive assessment. The required editorial synthesis: the week's central conclusion, two to four supporting signals and the most important meeting consequence.
3. Evidence and coverage health. GitHub scope, ClickUp freshness, reconciliation counts and any degraded input.
4. ClickUp structure and movement. The observed top-level hierarchy, material movement, quiet branches and PM-only work.
5. Material work areas. Evidence-led explanation of the branches that most affect delivery, decisions or risk. GitHub facts appear inside their mapped context.
6. Cross-area dependencies. The small number of dependencies whose effect crosses a ClickUp branch, repository or provider boundary.
7. Risks and blockers. Prioritised interventions, with owner or decision path when the evidence supplies one.
8. Decisions required. A decision question, the evidence that bears on it, and the consequence of deferring it. A recommendation must be labelled as such.
9. Recommended priorities and meeting agenda. A bounded proposed order for the next period, followed by prepared contributor topics and one shared open floor. Meeting decisions and assignments remain human acts.
10. Evidence appendix. Complete GitHub coverage, ClickUp-only work, reconciliation exceptions, provenance and a locator for the detached final artifact receipt, after an explicit appendix divider.

The main narrative may include a contributor highlight, a claimed show-and-tell or a trend only when its reviewed input is present and it advances this arc. Upstream activity belongs in the live narrative only when the editorial analysis connects it to an in-scope dependency, risk or decision. Otherwise it remains in the appendix.

The feature-flagged transition preview is not yet a contributor-input path. It must identify that limitation in its receipt and is eligible for meeting use only when qualification proves that no ready exact-date contributor highlight, show-and-tell claim or prepared topic exists. A present reviewed submission must fail the transition qualification rather than disappear from the deck.

Required coverage

The live narrative must contain:

• one executive conclusion rather than a list of counts;
• every top-level ClickUp branch and its current coverage state;
• every red or publication-blocking data-quality condition;
• every decision selected as due in the meeting window;
• material unmapped, ambiguous or stale GitHub work;
• a bounded forward agenda; and
• a visible distinction between facts, interpretation and recommendations.

The appendix must contain every in-scope GitHub pull request and issue required by the report policy, including bot traffic and closed-without-merge records; all ClickUp-only work in scope; every reconciliation exception; source revisions and freshness; and a deterministic filename or stable delivery locator for the detached final artifact receipt.

The final artifact receipt is retained separately and generated after rendering. It records SHA-256 digests and byte sizes for the final deck files; publication verifies them against the delivered bytes. The appendix may display input provenance, but must not embed the final receipt or the deck's own output digests. The receipt must not include a digest of itself. This keeps the deck and receipt free of circular digest dependencies.

Forbidden patterns

The final deck must not contain:

• a fixed four-thread or repository-first structure when ClickUp supplies a current hierarchy;
• a standalone optional Model commentary block;
• model-invented tasks, owners, statuses, dependencies or GitHub–ClickUp links;
• progress percentages inferred from item counts unless ClickUp explicitly owns that metric and its denominator;
• a live slide that is only an exhaustive pull-request table;
• a chart whose only purpose is to decorate a status count;
• an empty placeholder slide for an optional submission;
• a silent omission caused by pagination, density or a missing provider;
• opaque graph identifiers in audience-facing prose when a human label exists; or
• celebratory, punitive or individual-performance framing.

Required editorial synthesis

Valid editorial analysis is a publication requirement. It must be produced as a structured, retained artifact before rendering. Failure after bounded attempts may produce an explicitly marked internal diagnostic draft, but it must fail the run and must not publish a final weekly deck.

The model must

• state an executive assessment grounded in cited evidence;
• identify material change and explain why it matters;
• connect explicit cross-branch and cross-repository dependencies;
• prioritise risks, decisions and recommended next attention;
• propose emphasis and ordering within the required narrative;
• write a conclusion-led headline and one take-away for each substantive live slide;
• cite the evidence records supporting every non-obvious factual claim; and
• state uncertainty or missing context rather than fill it in.

The model may

• compress several cited records into one explanation;
• compare the current observation with retained comparable history;
• recommend a meeting sequence, a follow-up question or a priority;
• select representative evidence for a live slide when required coverage is preserved elsewhere; and
• propose that explicitly linked records be discussed together.

The model must not

• change provider-owned values or reconciliation state;
• infer an unobserved relationship, owner, intention or cause;
• decide that required evidence is unimportant and hide it;
• turn a recommendation into an assignment or settled decision;
• quote or expose credentials, private tokens or unbounded untrusted text; or
• control HTML, CSS, Markdown directives, asset paths or renderer commands.

The following values remain exact provider facts: repository and record identity, URL, title, state, review/check result, release tag, ClickUp ancestry, priority, assignment, dependency, timestamps, counts, relationship state and source revision. A deterministic renderer may visibly truncate a long label with the full exact value retained in notes or the appendix; the model may not silently rewrite it.

Audience-facing citations should use familiar labels such as HSSM #123 or a ClickUp task name. Stable graph identifiers and full provenance belong in speaker notes and the appendix. A sentence that combines evidence and interpretation must still make the boundary clear.

Voice and terminology

• Use precise, plain, active language and sentence-case headings.
• Write for collaborators deciding what to do, not for a public launch or an automated changelog.
• Lead a slide with its conclusion: Release readiness is waiting on one owner, not Release readiness update.
• Keep a headline to at most 12 words and a take-away to one sentence of at most 28 words.
• Prefer concrete verbs: merged, failed, waits, blocks, depends, decide.
• Use recommendation, inference or uncertain when the statement is not a provider fact.
• State a real zero or quiet period plainly; do not manufacture momentum.
• Avoid hype, emoji, blame, rhetorical questions, unexplained acronyms and vague claims such as “good progress” or “needs attention”.
• Write HSSM and package names exactly as published. Define an unfamiliar technical term once.
• Use ClickUp hierarchy for the provider structure, work area for a human-readable branch in the narrative, and GitHub execution for issue, pull-request, review, check and release facts. Do not call every ClickUp level a thread.

Source and qualification annotations must be short and consistent. Visible body text names the familiar source; speaker notes hold exact record IDs, revisions and longer delivery context. Critical caveats cannot exist only in speaker notes.

Slide and density budget

The live narrative, including cover and reviewed contributor submissions, targets 12–18 slides and has a hard limit of 24. The evidence appendix does not count toward that limit and is not part of the default live walk-through.

If required live content cannot fit, composition fails with the sections and submissions that exceeded the budget. It must not drop them, reduce text below the approved minimum or move a required decision silently into the appendix.

For each live slide:

• express one decision, conclusion or orientation task;
• use at most eight short bullet lines or the visual equivalent;
• use at most one primary diagram, or two directly comparable charts;
• use no more than six body rows in a decision table; paginate or move detail to the appendix;
• keep one take-away visible on substantive slides; and
• prefer a new slide or summary over the dense layout.

Normal body text is 23 px with 1.34 line height. The 20 px dense variant with 1.28 line height is allowed only after rendered overflow is detected, never as the default. Nothing important may occupy the 70 px footer reserve. Every continuation slide repeats enough context to stand alone and says that it is a continuation.

Visual language

The visual authority is lnccbrown/hssm_design_system at commit 566f781, specifically its README.md, 20-surfaces.md and tokens.json. This document records deck-specific choices and does not duplicate the full brand system.

• Render at 1280 × 720 on the light slide theme.
• As a temporary deck-specific exception to the design system's cover-mark rule, use the indigo cover with one title and one subtitle line and no logo at this pinned revision: the design system does not yet provide a sanctioned white logo for the indigo ground. The existing on-dark logo is approved for navy grounds. Do not substitute it, synthesize a logo or recolour one. Adding a cover logo requires a separately reviewed specification revision that pins the approved asset.
• Top-align content and reserve the footer band for the reporting window and page number.
• Use IBM Plex Sans for prose and IBM Plex Mono only for code, commands, compact source labels and package roles.
• Use semantic tokens. The brand gradient appears only as the 2 px top rule. Do not add decorative gradients, shadows, glows or off-palette colours.
• Blocking, warning/decision and informational states always carry a word in addition to their status colour.
• Use cards and diagrams to show hierarchy, relationships or comparison, not to decorate prose.
• Put scientific plots and data charts on white paper. Label axes, series, units, window and comparison basis. Never use colour as the only series cue.
• Preserve the design system's Graphviz and roadmap-diagram semantics when those forms are used. Every diagram needs a readable legend or direct labels.
• Use only self-contained, reviewed assets in the final artifact.

Accessibility and projection acceptance

• Text contrast is at least 4.5:1; meaningful non-text marks are at least 3:1.
• Colour always has a redundant word, icon, pattern, line style or direct label.
• Every chart and diagram has a meaningful accessible name and a concise text equivalent in the slide or notes.
• Tables have headers and a logical reading order. Critical meaning must not depend on hover, animation or speaker notes.
• The HTML deck remains navigable without a mouse and readable without scripting; print/PDF output includes every slide.
• Inspect the densest slide, every diagram, every continuation and the appendix boundary at full 1280 × 720 size. Nothing may clip, scroll inside a slide, overlap the footer or rely on browser zoom.
• Inspect at projector distance: 23 px body text is the norm, 20 px is the absolute live-slide minimum, and compact appendix text is never used in the live narrative.

Worked example

This example tests structure and editorial behaviour; the names and numbers are fictional.

Input observation

• ClickUp ancestry: HSSM Roadmap / Reliability / Release readiness / Now.
• Task Qualify pandas 3 is in progress and explicitly represents LANfactory #145, whose GitHub checks are red.
• Task Choose release owner is ClickUp-only, marked urgent and unassigned.
• HSSM #200 is in the GitHub scope and unmapped.
• One GitHub issue has two candidate ClickUp tasks and is ambiguous.
• Two releases shipped and the open pull-request stock increased by three.

Acceptable live treatment

• Executive headline: Two releases shipped; an urgent ownership task is unassigned.
• The ClickUp overview shows Reliability in its observed position and marks the owner task PM-only.
• The work-area slide keeps LANfactory #145 red because GitHub owns the check result; it does not copy a green ClickUp status over it.
• The decision slide asks who owns the release and labels any proposed person as a recommendation.
• Coverage health reports one unmapped and one ambiguous GitHub record. HSSM #200 appears under Not yet mapped in ClickUp, and the ambiguous issue is attached to neither candidate task.
• The appendix retains every record and relationship used above.

Unacceptable treatment

• Great progress across all four threads: hype, fixed structure and an unsupported universal claim.
• Placing the ambiguous issue under the most similar task: inferred mapping.
• Ownership blocks the next step without an observed blocker or dependency: an unsupported causal claim. Urgency and lack of assignment alone do not establish a blocker.
• Reporting Qualify pandas 3 is on track from ClickUp while GitHub checks are red: authority violation.
• Omitting HSSM #200 because it lacks a ClickUp task: transition coverage violation.

Acceptance cases

Case	The implementation passes when
Mixed transition coverage	Mapped work follows ClickUp; unmapped, ambiguous and PM-only work remain visibly distinct; GitHub coverage is complete.
Quiet top-level branch	The overview says there was no material movement without inventing a detailed slide or deleting the branch.
Permitted stale ClickUp reading	Transition output displays the observation time and degraded organisation; it does not present the reading as current or use the Git roadmap as fallback.
Stale relationship with fresh observations	Current provider facts keep their own freshness labels; the relationship is visibly unresolved; every candidate and its provenance is retained, and no candidate is used as a current placement.
Missing ClickUp in complete mode	The run retains diagnostics and fails before final publication.
Heavy GitHub week	The live narrative stays within 24 slides; selection is explained; every record remains in the appendix; no slide clips.
Required content over budget	Composition fails with an actionable list of the overflowing sections rather than silently dropping evidence or shrinking below 20 px.
Ambiguous relationship	Neither candidate hierarchy receives the record; the ambiguity is shown as a coverage or decision item.
ClickUp-only priority	The task appears in its hierarchy with a PM-only label and no invented repository activity.
Unsupported blocker inference	An urgent, unassigned task without an observed blocker or dependency is not described as blocking the next step.
Editorial model unavailable or invalid	Evidence and diagnostics are retained, any render is marked internal diagnostic, the run fails, and no final deck is published.
Zero movement	The deck reports zero plainly and does not replace it with vague positive language.
Visual projection	Full-size cover, densest live slide, diagrams, continuation slides and appendix boundary meet the density, contrast, labelling and footer rules.
Cover asset at the pinned revision	The indigo cover has a title and subtitle only; no navy-ground, recoloured or synthesized logo is used.
Detached final receipt	The appendix locates the separately retained receipt; its final-deck digests and byte sizes verify against delivered files, with no embedded output digest or receipt self-digest.
Reproduction	The same observations, editorial artifact, specification revision and renderer produce byte-identical deterministic outputs.

Approval, versioning and change control

Merging the pull request that introduces a revision records the report owner's approval. The final report receipt must later record this file's repository revision, relative path and SHA-256 digest. Historical reproduction uses that exact revision rather than the newest specification.

A separately reviewed specification revision is required for changes to:

• audience, purpose or decisions supported;
• provider authority, hierarchy or reconciliation treatment;
• required, optional or forbidden narrative sections;
• the model's required status, responsibilities or factual limits;
• voice, terminology, headline or annotation rules;
• live slide count, density or overflow policy;
• the pinned design-system revision or semantic visual rules;
• accessibility and projection requirements;
• acceptance cases or final-publication failure policy; or
• the approval mechanism itself.

Weekly evidence, copy generated from an already approved editorial schema, non-semantic typo fixes, and renderer refactors proven visually equivalent do not create a new product revision. A design, prompt or composer change must not quietly change this contract; if equivalence is debatable, review a new revision.