diff --git a/packages/cli/src/commands/coreSkillContent.test.ts b/packages/cli/src/commands/coreSkillContent.test.ts
index c537dc9d1..e7578ed58 100644
--- a/packages/cli/src/commands/coreSkillContent.test.ts
+++ b/packages/cli/src/commands/coreSkillContent.test.ts
@@ -35,6 +35,20 @@ describe("hyperframes-core contract docs", () => {
     expect(renderReference).toContain("OUTCOME:");
     expect(renderReference).toContain("WORKAROUND:");
   });
+
+  it("mandates a composition-structure block for visual-defect feedback", () => {
+    const skill = read("skills", "hyperframes-cli", "SKILL.md");
+    const renderReference = read("skills", "hyperframes-cli", "references", "preview-render.md");
+
+    // Skill teaches the mandate at a high level.
+    expect(skill).toContain("COMPOSITION_STRUCTURE:");
+    // Reference carries the fillable block + agent-helper pointer.
+    expect(renderReference).toContain("COMPOSITION_STRUCTURE:");
+    expect(renderReference).toContain("elements: video=");
+    expect(renderReference).toContain("attributes:");
+    expect(renderReference).toContain("timeline:");
+    expect(renderReference).toContain("buildCompositionCensus");
+  });
 });
 
 describe("media-use TTS documentation", () => {
diff --git a/packages/cli/src/commands/feedback.ts b/packages/cli/src/commands/feedback.ts
index d4eb23fba..fc06b0cd8 100644
--- a/packages/cli/src/commands/feedback.ts
+++ b/packages/cli/src/commands/feedback.ts
@@ -12,6 +12,7 @@ import { buildIssueUrl, HYPERFRAMES_REPO_URL } from "../utils/feedbackIssue.js";
 import { VERSION } from "../version.js";
 import { c } from "../ui/colors.js";
 import { parseFeedbackRating } from "../utils/feedbackRating.js";
+import { lintFeedbackComment } from "../utils/feedbackLint.js";
 
 export const examples: Example[] = [
   ["Submit render feedback", 'hyperframes feedback --rating 8 --comment "fast but font missing"'],
@@ -156,6 +157,13 @@ export default defineCommand({
     const comment = normalizeComment(args.comment);
     const doctorSummary = await getDoctorSummary();
 
+    // Soft-warn (never blocks) when the comment for a non-clean report is
+    // missing the mandated reproduction-packet markers. Prints before the
+    // submission ack so the reporter sees the nudge while their run is fresh.
+    for (const warning of lintFeedbackComment({ rating, comment })) {
+      console.log(c.warn(`⚠ ${warning.message}`));
+    }
+
     // The standalone command runs separately from `render`, so it has no real
     // elapsed time to report. Omit it rather than recording a fake duration.
     trackRenderFeedback({ rating, comment, doctorSummary });
diff --git a/packages/cli/src/utils/compositionCensus.test.ts b/packages/cli/src/utils/compositionCensus.test.ts
new file mode 100644
index 000000000..ec9ee5224
--- /dev/null
+++ b/packages/cli/src/utils/compositionCensus.test.ts
@@ -0,0 +1,135 @@
+import { describe, expect, it } from "vitest";
+
+import { buildCompositionCensus, renderCompositionCensusBlock } from "./compositionCensus.js";
+
+const MINIMAL_HTML = `<!doctype html>
+<html>
+  <body>
+    <div data-composition-id="main" data-start="0" data-duration="5"></div>
+  </body>
+</html>`;
+
+const RICH_HTML = `<!doctype html>
+<html>
+  <head>
+    <style>
+      .card { filter: blur(4px); mix-blend-mode: multiply; }
+      .fixed-bar { position: fixed; overflow: hidden; }
+    </style>
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>
+  </head>
+  <body>
+    <div data-composition-id="main" data-start="0" data-duration="10">
+      <video data-has-audio="true"></video>
+      <video></video>
+      <audio></audio>
+      <img />
+      <img />
+      <img />
+      <svg></svg>
+      <canvas></canvas>
+      <div data-composition-src="scenes/intro.html" data-start="0"></div>
+      <div data-composition-src="scenes/outro.html" data-start="5"></div>
+      <div style="clip-path: circle(50%); transform: translateX(10px); z-index: 3"></div>
+      <div style="background-image: url('bg.png')"></div>
+      <div style="mask-image: url('mask.svg')"></div>
+    </div>
+    <script>
+      gsap.timeline().to(".card", { x: 100 });
+    </script>
+  </body>
+</html>`;
+
+describe("buildCompositionCensus", () => {
+  it("counts zero media on a minimal composition", () => {
+    const c = buildCompositionCensus(MINIMAL_HTML);
+    expect(c.elementCensus).toEqual({
+      video: 0,
+      audio: 0,
+      img: 0,
+      svg: 0,
+      canvas: 0,
+      subCompositionMounts: 0,
+    });
+    expect(c.timelineShape.nested).toBe(false);
+    expect(c.timelineShape.subCompositionCount).toBe(0);
+    expect(c.timelineShape.usesGsap).toBe(false);
+    expect(c.timelineShape.usesDataTimeline).toBe(true);
+  });
+
+  it("counts each element category on a rich composition", () => {
+    const c = buildCompositionCensus(RICH_HTML);
+    expect(c.elementCensus).toEqual({
+      video: 2,
+      audio: 1,
+      img: 3,
+      svg: 1,
+      canvas: 1,
+      subCompositionMounts: 2,
+    });
+  });
+
+  it("detects structural attributes from both inline style and <style> rules", () => {
+    const c = buildCompositionCensus(RICH_HTML);
+    // Inline-style probes
+    expect(c.structuralAttributes.clipPath).toBe(true);
+    expect(c.structuralAttributes.transform).toBe(true);
+    expect(c.structuralAttributes.zIndex).toBe(true);
+    expect(c.structuralAttributes.backgroundImage).toBe(true);
+    expect(c.structuralAttributes.maskImage).toBe(true);
+    // <style> tag probes
+    expect(c.structuralAttributes.filter).toBe(true);
+    expect(c.structuralAttributes.mixBlendMode).toBe(true);
+    expect(c.structuralAttributes.positionFixed).toBe(true);
+    expect(c.structuralAttributes.overflowHidden).toBe(true);
+    // data-* attribute probes
+    expect(c.structuralAttributes.dataHasAudio).toBe(true);
+    expect(c.structuralAttributes.dataDuration).toBe(true);
+    expect(c.structuralAttributes.dataStart).toBe(true);
+    expect(c.structuralAttributes.dataCompositionSrc).toBe(true);
+  });
+
+  it("reports absent attributes as false on minimal HTML", () => {
+    const c = buildCompositionCensus(MINIMAL_HTML);
+    expect(c.structuralAttributes.clipPath).toBe(false);
+    expect(c.structuralAttributes.filter).toBe(false);
+    expect(c.structuralAttributes.mixBlendMode).toBe(false);
+    expect(c.structuralAttributes.dataHasAudio).toBe(false);
+    expect(c.structuralAttributes.backgroundImage).toBe(false);
+    expect(c.structuralAttributes.maskImage).toBe(false);
+  });
+
+  it("detects gsap from both script src and inline gsap.* calls", () => {
+    expect(buildCompositionCensus(RICH_HTML).timelineShape.usesGsap).toBe(true);
+    const inlineOnly = `<html><body><div data-composition-id="m"></div><script>gsap.to('.x', {})</script></body></html>`;
+    expect(buildCompositionCensus(inlineOnly).timelineShape.usesGsap).toBe(true);
+    const noGsap = `<html><body><div data-composition-id="m"></div><script>console.log('hi')</script></body></html>`;
+    expect(buildCompositionCensus(noGsap).timelineShape.usesGsap).toBe(false);
+  });
+
+  it("marks timelines as nested when sub-comp mounts exist", () => {
+    const c = buildCompositionCensus(RICH_HTML);
+    expect(c.timelineShape.nested).toBe(true);
+    expect(c.timelineShape.subCompositionCount).toBe(2);
+  });
+});
+
+describe("renderCompositionCensusBlock", () => {
+  it("emits a REPRO-packet-compatible block starting with the mandated header", () => {
+    const block = renderCompositionCensusBlock(buildCompositionCensus(RICH_HTML));
+    expect(block.startsWith("COMPOSITION_STRUCTURE:")).toBe(true);
+    expect(block).toContain("elements: video=2 audio=1 img=3 svg=1 canvas=1 subComps=2");
+    expect(block).toContain("attributes:");
+    expect(block).toContain("timeline: nested (2 sub-comps); driver=gsap+data-timeline");
+    // Placeholder slots the parser can't infer.
+    expect(block).toContain("delta:");
+    expect(block).toContain("defect:");
+  });
+
+  it("emits '(none present)' on the attributes line when no structural attrs are found", () => {
+    const empty = `<html><body><div data-composition-id="m"></div></body></html>`;
+    const block = renderCompositionCensusBlock(buildCompositionCensus(empty));
+    expect(block).toContain("attributes: (none present)");
+    expect(block).toContain("timeline: flat; driver=none");
+  });
+});
diff --git a/packages/cli/src/utils/compositionCensus.ts b/packages/cli/src/utils/compositionCensus.ts
new file mode 100644
index 000000000..fdefd048f
--- /dev/null
+++ b/packages/cli/src/utils/compositionCensus.ts
@@ -0,0 +1,234 @@
+import { parseHTML } from "linkedom";
+
+/**
+ * A privacy-preserving structural anatomy of a HyperFrames composition. The
+ * agent fills this before submitting a non-clean `hyperframes feedback` so
+ * maintainers can pattern-match the report against known bug families without
+ * receiving the composition ZIP.
+ *
+ * Counts and presence flags only — no file paths, no src URLs, no user text.
+ */
+export interface CompositionCensus {
+  /** Counts of media/graphic elements at the failing HTML pass. */
+  elementCensus: {
+    video: number;
+    audio: number;
+    img: number;
+    svg: number;
+    canvas: number;
+    /** Sub-composition mount points (elements with `data-composition-src`). */
+    subCompositionMounts: number;
+  };
+  /**
+   * Union set of structural attributes present anywhere in the composition.
+   * Each key is HF's capture-routing signal set (see references/preview-render.md).
+   */
+  structuralAttributes: {
+    clipPath: boolean;
+    filter: boolean;
+    mixBlendMode: boolean;
+    transform: boolean;
+    mask: boolean;
+    positionFixed: boolean;
+    overflowHidden: boolean;
+    zIndex: boolean;
+    dataHasAudio: boolean;
+    dataDuration: boolean;
+    dataStart: boolean;
+    dataCompositionSrc: boolean;
+    backgroundImage: boolean;
+    maskImage: boolean;
+  };
+  /**
+   * Timeline shape summary. Distinguishes flat single-composition renders
+   * from nested sub-composition trees, and GSAP-driven vs data-attribute-driven.
+   */
+  timelineShape: {
+    /** True if any `data-composition-src` mount exists. */
+    nested: boolean;
+    /** Count of sub-composition mounts (`data-composition-src` count). */
+    subCompositionCount: number;
+    /** Any GSAP timeline usage (script tags referencing gsap or data-gsap-*). */
+    usesGsap: boolean;
+    /** Any element carrying `data-start` or `data-duration`. */
+    usesDataTimeline: boolean;
+  };
+}
+
+const SUB_COMPOSITION_SELECTOR = "[data-composition-src]";
+const DATA_HAS_AUDIO_SELECTOR = "[data-has-audio]";
+const DATA_DURATION_SELECTOR = "[data-duration]";
+const DATA_START_SELECTOR = "[data-start]";
+
+// Values that should NOT count as a "filter"/"mask"/"transform" attribute — the
+// browser default. Explicit "none" is authored intent to disable, still counts
+// as noteworthy for the census (author touched the property).
+const EMPTY_VALUES = new Set(["", "initial", "unset"]);
+
+function hasNonEmptyInlineStyle(el: Element, property: string): boolean {
+  const raw = el.getAttribute("style");
+  if (!raw) return false;
+  // Case-insensitive property match. We intentionally do NOT parse CSS
+  // shorthand-style semantics — a `background: url(...)` in the shorthand
+  // still surfaces via a substring probe of the property token, which is
+  // sufficient for structural presence signaling.
+  const target = property.toLowerCase();
+  const declarations = raw.split(";");
+  for (const decl of declarations) {
+    const colon = decl.indexOf(":");
+    if (colon <= 0) continue;
+    const prop = decl.slice(0, colon).trim().toLowerCase();
+    const value = decl.slice(colon + 1).trim();
+    if (prop === target && !EMPTY_VALUES.has(value.toLowerCase())) return true;
+  }
+  return false;
+}
+
+function anyElementHasInlineStyle(doc: Document, property: string): boolean {
+  const all = doc.querySelectorAll("[style]");
+  for (const el of Array.from(all)) {
+    if (hasNonEmptyInlineStyle(el as unknown as Element, property)) return true;
+  }
+  return false;
+}
+
+function hasStyleTagReferencing(doc: Document, needle: RegExp): boolean {
+  const styles = doc.querySelectorAll("style");
+  for (const styleEl of Array.from(styles)) {
+    const text = (styleEl as unknown as Element).textContent ?? "";
+    if (needle.test(text)) return true;
+  }
+  return false;
+}
+
+function detectGsap(doc: Document): boolean {
+  const scripts = doc.querySelectorAll("script");
+  for (const script of Array.from(scripts)) {
+    const el = script as unknown as Element;
+    const src = el.getAttribute("src") ?? "";
+    if (/gsap/i.test(src)) return true;
+    const text = el.textContent ?? "";
+    if (/\bgsap\.(timeline|to|from|fromTo|set)\b/.test(text)) return true;
+  }
+  return false;
+}
+
+/**
+ * Build a structural census of a composition HTML document. Counts elements
+ * and probes for structural attributes without reading any user-supplied
+ * strings (paths, src URLs, text content) beyond what's needed to detect
+ * presence.
+ *
+ * Safe to call on partial/malformed HTML — linkedom's parser tolerates the
+ * usual authoring accidents and the census reports zeros for missing sections.
+ */
+export function buildCompositionCensus(html: string): CompositionCensus {
+  const doc = parseHTML(html).document as unknown as Document;
+
+  const count = (selector: string): number => doc.querySelectorAll(selector).length;
+
+  const subCompositionCount = count(SUB_COMPOSITION_SELECTOR);
+
+  // Inline-style presence probes. Class-based rules would require full CSS
+  // parsing — out of scope here. But we also check <style> tag contents as a
+  // best-effort catch for authored stylesheets in the same file.
+  const anyStyle = (property: string, styleRegex: RegExp): boolean =>
+    anyElementHasInlineStyle(doc, property) || hasStyleTagReferencing(doc, styleRegex);
+
+  return {
+    elementCensus: {
+      video: count("video"),
+      audio: count("audio"),
+      img: count("img"),
+      svg: count("svg"),
+      canvas: count("canvas"),
+      subCompositionMounts: subCompositionCount,
+    },
+    structuralAttributes: {
+      clipPath: anyStyle("clip-path", /clip-path\s*:/i),
+      filter: anyStyle("filter", /(^|\s|\{)filter\s*:/i),
+      mixBlendMode: anyStyle("mix-blend-mode", /mix-blend-mode\s*:/i),
+      transform: anyStyle("transform", /(^|\s|\{)transform\s*:/i),
+      mask: anyStyle("mask", /(^|\s|\{)mask\s*:/i),
+      positionFixed:
+        anyElementHasInlineStyle(doc, "position") ||
+        hasStyleTagReferencing(doc, /position\s*:\s*fixed/i),
+      overflowHidden: hasStyleTagReferencing(doc, /overflow\s*:\s*hidden/i),
+      zIndex: anyStyle("z-index", /z-index\s*:/i),
+      dataHasAudio: count(DATA_HAS_AUDIO_SELECTOR) > 0,
+      dataDuration: count(DATA_DURATION_SELECTOR) > 0,
+      dataStart: count(DATA_START_SELECTOR) > 0,
+      dataCompositionSrc: subCompositionCount > 0,
+      backgroundImage: anyStyle("background-image", /background(-image)?\s*:[^;]*url\(/i),
+      maskImage: anyStyle("mask-image", /mask(-image)?\s*:[^;]*url\(/i),
+    },
+    timelineShape: {
+      nested: subCompositionCount > 0,
+      subCompositionCount,
+      usesGsap: detectGsap(doc),
+      usesDataTimeline: count(DATA_START_SELECTOR) + count(DATA_DURATION_SELECTOR) > 0,
+    },
+  };
+}
+
+/**
+ * Render the census as the exact `COMPOSITION_STRUCTURE:` block the skill
+ * mandates for non-10 visual-defect feedback. Reporter-friendly plain text:
+ * element counts, present attributes as a comma-joined list, and a compact
+ * timeline summary. Placeholder markers (`<...>`) are left for the reporter
+ * to fill in for delta/defect location — those slots the parser can't infer
+ * from HTML alone.
+ */
+export function renderCompositionCensusBlock(census: CompositionCensus): string {
+  const { elementCensus, structuralAttributes, timelineShape } = census;
+
+  const elementLine = [
+    `video=${elementCensus.video}`,
+    `audio=${elementCensus.audio}`,
+    `img=${elementCensus.img}`,
+    `svg=${elementCensus.svg}`,
+    `canvas=${elementCensus.canvas}`,
+    `subComps=${elementCensus.subCompositionMounts}`,
+  ].join(" ");
+
+  const attrPresent: string[] = [];
+  const push = (key: keyof CompositionCensus["structuralAttributes"], label: string): void => {
+    if (structuralAttributes[key]) attrPresent.push(label);
+  };
+  push("clipPath", "clip-path");
+  push("filter", "filter");
+  push("mixBlendMode", "mix-blend-mode");
+  push("transform", "transform");
+  push("mask", "mask");
+  push("positionFixed", "position:fixed");
+  push("overflowHidden", "overflow:hidden");
+  push("zIndex", "z-index");
+  push("dataHasAudio", "data-has-audio");
+  push("dataDuration", "data-duration");
+  push("dataStart", "data-start");
+  push("dataCompositionSrc", "data-composition-src");
+  push("backgroundImage", "background-image:url");
+  push("maskImage", "mask-image:url");
+
+  const attrLine = attrPresent.length > 0 ? attrPresent.join(", ") : "(none present)";
+
+  const shape = timelineShape.nested
+    ? `nested (${timelineShape.subCompositionCount} sub-comps)`
+    : "flat";
+  const driver =
+    [
+      timelineShape.usesGsap ? "gsap" : null,
+      timelineShape.usesDataTimeline ? "data-timeline" : null,
+    ]
+      .filter(Boolean)
+      .join("+") || "none";
+
+  return [
+    "COMPOSITION_STRUCTURE:",
+    `  elements: ${elementLine}`,
+    `  attributes: ${attrLine}`,
+    `  timeline: ${shape}; driver=${driver}`,
+    "  delta: <what differs between the working workaround-render and the broken default render>",
+    "  defect: <spatial location + frame index range, e.g. top-left / frames 0-30 — omit for non-visual defects>",
+  ].join("\n");
+}
diff --git a/packages/cli/src/utils/feedbackLint.test.ts b/packages/cli/src/utils/feedbackLint.test.ts
new file mode 100644
index 000000000..a4c94bcf3
--- /dev/null
+++ b/packages/cli/src/utils/feedbackLint.test.ts
@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  COMPOSITION_STRUCTURE_RATING_CEILING,
+  VISUAL_DEFECT_KEYWORDS,
+  lintFeedbackComment,
+  mentionsVisualDefect,
+} from "./feedbackLint.js";
+
+describe("lintFeedbackComment", () => {
+  it("returns no warnings for a perfect rating regardless of comment", () => {
+    expect(lintFeedbackComment({ rating: 10, comment: "black frame at 0.5s, no REPRO" })).toEqual(
+      [],
+    );
+  });
+
+  it("returns no warnings when the comment is missing or blank", () => {
+    expect(lintFeedbackComment({ rating: 6, comment: undefined })).toEqual([]);
+    expect(lintFeedbackComment({ rating: 6, comment: "" })).toEqual([]);
+    expect(lintFeedbackComment({ rating: 6, comment: "   \n  " })).toEqual([]);
+  });
+
+  it("warns on non-10 comments missing REPRO COMMAND:", () => {
+    const warnings = lintFeedbackComment({
+      rating: 6,
+      comment: "fast but crashed after a bit",
+    });
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.code).toBe("missing-repro-command");
+    expect(warnings[0]?.message).toContain("REPRO COMMAND:");
+  });
+
+  it("stays silent when the reporter already included a REPRO COMMAND: block", () => {
+    const warnings = lintFeedbackComment({
+      rating: 4,
+      comment: [
+        "cloudrun submission kept timing out.",
+        "REPRO COMMAND: cd project && npx hyperframes cloudrun submit",
+        "EXPECTED / ACTUAL: uploads / hangs at seek",
+      ].join("\n"),
+    });
+    expect(warnings).toEqual([]);
+  });
+
+  it("warns on rating<=7 visual-defect comments missing COMPOSITION_STRUCTURE:", () => {
+    const warnings = lintFeedbackComment({
+      rating: 5,
+      comment: [
+        "REPRO COMMAND: cd proj && npx hyperframes render",
+        "EXPECTED / ACTUAL: output correct / black frame at 0.5s",
+      ].join("\n"),
+    });
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.code).toBe("missing-composition-structure");
+    expect(warnings[0]?.message).toContain("COMPOSITION_STRUCTURE:");
+    expect(warnings[0]?.message).toContain("buildCompositionCensus");
+  });
+
+  it("skips the composition-structure warning above the rating ceiling", () => {
+    const warnings = lintFeedbackComment({
+      rating: COMPOSITION_STRUCTURE_RATING_CEILING + 1,
+      comment: [
+        "REPRO COMMAND: cd proj && npx hyperframes render",
+        "minor black bar on the right edge; workaround with --resolution landscape",
+      ].join("\n"),
+    });
+    // Missing structure warning is suppressed at rating 8+.
+    expect(warnings.filter((w) => w.code === "missing-composition-structure")).toEqual([]);
+  });
+
+  it("skips the composition-structure warning when no visual-defect keyword is present", () => {
+    const warnings = lintFeedbackComment({
+      rating: 4,
+      comment: [
+        "docker mode always fails on Alpine",
+        "REPRO COMMAND: docker run ... && npx hyperframes doctor --docker",
+      ].join("\n"),
+    });
+    expect(warnings.filter((w) => w.code === "missing-composition-structure")).toEqual([]);
+  });
+
+  it("emits both warnings when a low-rating visual comment lacks both markers", () => {
+    const warnings = lintFeedbackComment({
+      rating: 3,
+      comment: "flickers at every scene boundary",
+    });
+    expect(new Set(warnings.map((w) => w.code))).toEqual(
+      new Set(["missing-repro-command", "missing-composition-structure"]),
+    );
+  });
+});
+
+describe("mentionsVisualDefect", () => {
+  it.each(VISUAL_DEFECT_KEYWORDS.map((kw) => kw as string))(
+    "matches keyword %j case-insensitively",
+    (kw) => {
+      expect(mentionsVisualDefect(`Reports a ${kw.toUpperCase()} issue`)).toBe(true);
+    },
+  );
+
+  it("returns false for comments about non-visual friction", () => {
+    expect(mentionsVisualDefect("cli hangs on init prompt in non-TTY shells")).toBe(false);
+    expect(mentionsVisualDefect("cloudrun deploy expired auth token")).toBe(false);
+  });
+});
diff --git a/packages/cli/src/utils/feedbackLint.ts b/packages/cli/src/utils/feedbackLint.ts
new file mode 100644
index 000000000..511559100
--- /dev/null
+++ b/packages/cli/src/utils/feedbackLint.ts
@@ -0,0 +1,111 @@
+import { FEEDBACK_RATING_SCALE } from "./feedbackRating.js";
+
+/**
+ * Keywords that suggest the reporter is describing a visual defect (as opposed
+ * to a build failure, missing feature, or plain workflow friction). When these
+ * appear in a non-10 feedback comment, the reporter should include a
+ * `COMPOSITION_STRUCTURE:` block so maintainers can pattern-match against
+ * known bug families without receiving the composition ZIP. Matched
+ * case-insensitively against the raw comment.
+ *
+ * Keep the list short and unambiguous — false positives are cheap (a soft
+ * warn), false negatives just mean the reporter skips the structure block on
+ * a non-visual bug, which is fine.
+ */
+export const VISUAL_DEFECT_KEYWORDS: readonly string[] = [
+  "black",
+  "flicker",
+  "corrupt",
+  "wrong frame",
+  "blank",
+  "visual",
+  "render",
+] as const;
+
+/**
+ * Ratings that should mandate `COMPOSITION_STRUCTURE:` when the comment
+ * contains a visual-defect keyword. 7 and below covers "clearly broken" —
+ * 8-9 are usually "worked, but noticed a nit" which doesn't need the full
+ * structural anatomy.
+ */
+export const COMPOSITION_STRUCTURE_RATING_CEILING = 7;
+
+const REPRO_MARKER = "REPRO COMMAND:";
+const STRUCTURE_MARKER = "COMPOSITION_STRUCTURE:";
+
+export interface FeedbackLintInput {
+  rating: number;
+  comment: string | undefined;
+}
+
+export interface FeedbackLintWarning {
+  code: "missing-repro-command" | "missing-composition-structure";
+  message: string;
+}
+
+/**
+ * Soft-warn lint on the `hyperframes feedback` comment body. Never blocks
+ * submission — some legitimate reports (a one-line "cloudrun quota bumped
+ * yesterday, fine now") won't fit the mold. The warning is just a nudge and
+ * a pointer to the auto-census helper.
+ *
+ * Rules:
+ *  1. `rating === 10` — no check. A perfect run doesn't need a repro packet.
+ *  2. Comment missing / empty — no check. `feedback --rating 6` with no
+ *     comment is a valid quick vote; the maintainer sees rating drift without
+ *     the reporter having to synthesize a fake repro.
+ *  3. Comment present + rating < 10 + no `REPRO COMMAND:` — warn.
+ *  4. Comment present + rating ≤ 7 + visual-defect keyword + no
+ *     `COMPOSITION_STRUCTURE:` — warn (in addition to any #3 warning).
+ */
+export function lintFeedbackComment(input: FeedbackLintInput): FeedbackLintWarning[] {
+  const { rating, comment } = input;
+  if (rating === FEEDBACK_RATING_SCALE) return [];
+  const trimmed = comment?.trim();
+  if (!trimmed) return [];
+
+  const warnings: FeedbackLintWarning[] = [];
+
+  if (!trimmed.includes(REPRO_MARKER)) {
+    warnings.push({
+      code: "missing-repro-command",
+      message: [
+        `Comment on a ${rating}/${FEEDBACK_RATING_SCALE} report is missing a "${REPRO_MARKER}" block —`,
+        "maintainers can't rerun the failure from a symptom summary alone.",
+        "See `references/preview-render.md` → feedback for the required packet shape.",
+      ].join(" "),
+    });
+  }
+
+  if (
+    rating <= COMPOSITION_STRUCTURE_RATING_CEILING &&
+    mentionsVisualDefect(trimmed) &&
+    !trimmed.includes(STRUCTURE_MARKER)
+  ) {
+    warnings.push({
+      code: "missing-composition-structure",
+      message: [
+        `Comment describes a visual defect at ${rating}/${FEEDBACK_RATING_SCALE} but omits a`,
+        `"${STRUCTURE_MARKER}" block. Agents can auto-fill this via the composition-census helper`,
+        "(`buildCompositionCensus`/`renderCompositionCensusBlock` in `packages/cli/src/utils/compositionCensus.ts`)",
+        "so maintainers can pattern-match against known bug families without the composition ZIP.",
+      ].join(" "),
+    });
+  }
+
+  return warnings;
+}
+
+/**
+ * Case-insensitive substring probe against `VISUAL_DEFECT_KEYWORDS`. Exposed
+ * for tests and reuse; keywords are matched anywhere in the comment (no word
+ * boundaries) since real reports mix them into free prose. False positives
+ * cost one soft warn, which is acceptable.
+ */
+export function mentionsVisualDefect(comment: string): boolean {
+  const lower = comment.toLowerCase();
+  for (const kw of VISUAL_DEFECT_KEYWORDS) {
+    if (lower.includes(kw)) return true;
+  }
+  return false;
+}
diff --git a/skills-manifest.json b/skills-manifest.json
index 4982b60c9..7119d5c7b 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -26,7 +26,7 @@
       "files": 102
     },
     "hyperframes-cli": {
-      "hash": "79ab5a7856a42d68",
+      "hash": "8bee5964bf77cc24",
       "files": 11
     },
     "hyperframes-core": {
diff --git a/skills/hyperframes-cli/SKILL.md b/skills/hyperframes-cli/SKILL.md
index 464b37116..eed35a853 100644
--- a/skills/hyperframes-cli/SKILL.md
+++ b/skills/hyperframes-cli/SKILL.md
@@ -104,7 +104,7 @@ After verifying a successful render, send one feedback report unless telemetry i
 npx hyperframes feedback --rating <0-10> --comment "<specific result or friction>"
 ```
 
-Keep clean-run feedback concise. For any bug or friction, capture a **reproduction packet** before submitting; do not send only a symptom summary. Include the rerunnable command and working directory, expected versus actual behavior, exact error, whether output completed/fell back/failed, workaround, and repro-project status. If the issue did not reproduce again, say so and still include the last failing command and logs. Use `--file-issue` only with consent: it publishes a minimal reproduction to a public URL. The required packet format and privacy warning live in `references/preview-render.md`.
+Keep clean-run feedback concise. For any bug or friction, capture a **reproduction packet** before submitting; do not send only a symptom summary. Include the rerunnable command and working directory, expected versus actual behavior, exact error, whether output completed/fell back/failed, workaround, and repro-project status. For a rating ≤ 7 that describes a visual defect (black frame, flicker, corrupt output, wrong frame, blank output, other visual anomaly), also include a `COMPOSITION_STRUCTURE:` block — a privacy-preserving structural anatomy (element census + attribute presence + timeline shape) so maintainers can pattern-match against known bug families without the composition ZIP. Agents auto-fill this via the composition-census helper; the human user does not fill it by hand. If the issue did not reproduce again, say so and still include the last failing command and logs. Use `--file-issue` only with consent: it publishes a minimal reproduction to a public URL. The required packet format and privacy warning live in `references/preview-render.md`.
 
 ## Read the matching reference before running a command
 
diff --git a/skills/hyperframes-cli/references/preview-render.md b/skills/hyperframes-cli/references/preview-render.md
index add3d9bb8..c7562cdd9 100644
--- a/skills/hyperframes-cli/references/preview-render.md
+++ b/skills/hyperframes-cli/references/preview-render.md
@@ -161,10 +161,20 @@ EXPECTED / ACTUAL: <expected behavior> / <observed behavior and isolated trigger
 EXACT ERROR: <verbatim error or warning; include frame/timestamp for visual defects>
 OUTCOME: <output correct | output corrupt | fallback succeeded | hard exit | command hung>
 WORKAROUND: <exact workaround, or none>
+COMPOSITION_STRUCTURE:
+  elements: video=<n> audio=<n> img=<n> svg=<n> canvas=<n> subComps=<n>
+  attributes: <comma-joined subset of clip-path, filter, mix-blend-mode, transform, mask, position:fixed, overflow:hidden, z-index, data-has-audio, data-duration, data-start, data-composition-src, background-image:url, mask-image:url — or "(none present)">
+  timeline: <flat | nested (<n> sub-comps)>; driver=<gsap | data-timeline | gsap+data-timeline | none>
+  delta: <what differs between the working workaround-render and the broken default render>
+  defect: <spatial location + frame index range, e.g. top-left / frames 0-30 — omit for non-visual defects>
 ```
 
+`COMPOSITION_STRUCTURE:` is a privacy-preserving structural anatomy: counts + presence flags only, no file paths, no src URLs, no user text. It lets maintainers pattern-match the report against known bug families (e.g. "sub-comp mount + clip-path", "GSAP timeline + z-index") without receiving the composition ZIP. Required for any rating ≤ 7 that describes a visual defect (black frame, flicker, corrupt output, wrong frame, blank output, other visual anomaly); optional but appreciated on higher ratings. Agents on this skill can auto-fill the block by calling `buildCompositionCensus(html)` and `renderCompositionCensusBlock(census)` from `packages/cli/src/utils/compositionCensus.ts` against the composition HTML they already have access to — the human user does not fill this out by hand.
+
 Preserve paths containing spaces, flags, and relevant `HF_*` / `PRODUCER_*` variables; redact secrets and credentials. If the failure no longer reproduces, include the last failing command and log excerpt. Share a project link only when one is already available and safe to share.
 
+The `hyperframes feedback` command soft-warns when a non-10 `--comment` is missing `REPRO COMMAND:`, and when a rating-≤-7 visual-defect comment is missing `COMPOSITION_STRUCTURE:`. The warnings print above the submission ack and do not block — some legitimate reports (a one-line "cloudrun quota bumped yesterday, fine now") won't fit the mold. Fix the packet and rerun to silence them.
+
 Hit a reproducible bug? Add `--file-issue` (optionally `--dir <project>` and `--yes` for non-interactive shells) to also publish a minimal repro to a public URL and open a pre-filled GitHub `bug` issue draft for a maintainer to file. This publishes the project publicly, so it is opt-in and consent-gated; the issue is never auto-submitted.
 
 ## publish
