infocard-rebuild-template-grill

name	infocard-rebuild-template-grill
description	Use when building a high-density infocard for an open-source repository or technical analysis article. Covers both first-time creation and full reconstruction. Preserves the Swiss red-black UI style, chapter organization, and a 3-round maximum grill-me alignment flow before writing. Use when the user wants a build skill, not merely a content expansion patch.

Infocard Build Template + Grill Alignment

Use this skill when building OR rebuilding a high-density infocard for an open-source repository or technical analysis article.

Build = first-time creation from source material. Rebuild = re-do structure, CSS, and visual system from scratch — does NOT mean adding more content to the old layout while carrying bugs forward.

This skill is the authoritative reference for this user's infocard workflow. Do not substitute other skills, do not skip the grill-me phase unless the request is already fully specified, and do not stop at code changes — always verify the rendered result.

Known pitfalls / debugging (session 2026-07-22):

• Table mobile overflow: .comp-table inside a .card swallows overflow-x: auto due to block formatting context isolation. Fix: wrap table in <div style="overflow-x:auto;-webkit-overflow-scrolling:touch"> — see infocard-three-stage-pipeline SKILL.md for the exact pattern. Each </table> must close its wrapper </div>. Test with 390px viewport.

Image insertion scope rule (session 2026-06-03): When the user provides a source URL for image insertion, always confirm the target card by name/slug before writing. The fact that we just edited Card X is NOT sufficient evidence that the image belongs to Card X. See references/2026-06-03-image-scope-error-and-expansion-spec.md.

"Expand to 3x" rule (session 2026-06-03): When the user says "expand to 3x" or "content is too sparse," every module needs substantive explanation, workflow, caveats, and boundary conditions — not just more listed items. See references/2026-06-03-image-scope-error-and-expansion-spec.md.

For rebuild-style infocards, treat these as hard rules unless the user says otherwise:

Core interpretation rule

When the user says "build": create from source material, full structure from scratch.

When the user says "rebuild": do NOT merely add content to the old layout. The structure, CSS, and visual system must also be re-done from scratch — old bugs must not be carried forward. "Rebuild" ≠ "expand".

When the user says "expand" / "update" / "make it denser": preserve the chapter skeleton and visual style, but increase content depth, examples, evidence, and explanation density. Do not leave the old layout rough and call it done.

This was the user's explicit correction: prior sessions showed that "rebuild" was being interpreted as "add more text on top of the old layout" which preserved the original bugs. The user explicitly rejected this. The correct interpretation is: structure replaced, CSS replaced, old bugs gone, content preserved (or explicitly adjusted by user).

Hard reminder: if the user says "我是说重建信息卡" or similar, treat it as a strict rebuild directive, not a request for extra density or a style-only patch. Do not continue the grill-me phase unless the user re-opens scope.

vxtwitter API truncation pattern (2026-06-03)

For x.com/i/status/<id> links, use https://api.vxtwitter.com/status/<id>:

• Returns JSON with text, user_name, user_screen_name, date, likes/retweets/replies, hasMedia, mediaURLs[]
• Truncation behavior: text is truncated (~100 chars) when tweet is long, but mediaURLs[] stays complete
• When len(text) < 200 and hasMedia: true → content is primarily in the image
• Card title strategy: extract "what this tweet argues" from partial text, note "完整内容在配图中"
• Insert mediaURLs[0] (largest width) as content source in the card
• fxtwitter.com works for HTML but needs JS; mobile.twitter.com is blocked; other proxies 404

Mandatory output style

Preserve the following visual identity:

• Swiss / high-density layout
• red / black / white palette with restrained accent colors
• IBM Plex Sans + IBM Plex Mono typography or visually equivalent mono/sans pairing
• dense but readable modules
• strong section headers, compact metadata blocks, and crisp callouts
• mobile-first resilience: no horizontal overflow, no clipped text, no tiny unreadable text

Avoid:

• soft pastel UI
• large decorative illustrations that reduce density
• excessive whitespace that breaks the archive-card feel
• arbitrary font switching
• layout tweaks that only hide bugs instead of fixing the structure

Fixed chapter organization

Keep the content organization in a stable card-like hierarchy.

For open-source repository infocards

Use this default chapter order:

1. Header / project identity
2. One-line judgment / core take
3. Architecture / system overview
4. Quick start / key usage path
5. Configuration / important knobs
6. Extension / contribution / plugin path
7. Artifact / output / deployment / verification
8. Boundary / suitable vs unsuitable users
9. Closing summary / sources

For technical analysis infocards

Use this default chapter order:

1. Header / subject identity
2. One-line judgment / core conclusion
3. Background / why it matters
4. Evidence / key facts / data points
5. Mechanism / architecture / causal chain
6. Case breakdown / examples / comparison
7. Configuration / parameters / workflow if relevant
8. Verification / limitations / risk / boundary
9. Closing summary / sources

Allowed variation

You may insert 1–2 topic-specific modules, but the overall skeleton should remain recognizable and reusable.

Grill-me alignment flow

Before drafting, run a maximum of 3 rounds of grill-me.

Grill order

1. Scope split — what category of infocard is this?
2. Chapter rigidity — how fixed should the chapter structure be?
3. Validation bar — what must be treated as hard acceptance rules?

Rules for grilling

• Ask one question per round.
• Ask in a compact A/B/C table.
• Provide a recommended answer.
• Stop after 3 rounds max.
• If the user wants a visual module removed but the data should survive, ask where the data should be re-housed before writing.
• If the request is about header density or edge distance, treat spacing as a structural header concern, not a global page resize.
• If the answer is already clear from the user request, skip to writing.
• Strict execution when user says "用 grill-me 对齐，次数不大于3"：必须显式问用户选择（A/B/C），不指定默认选项，等用户回复后再执行。不能直接默认执行推荐答案。

Preferred question shape

Use this format:

A	B	C
option 1	option 2	option 3

Then add a short recommendation: “我的推荐：X”.

Hard acceptance rules

Hard acceptance rules

• Content Density: When the user requests a rebuild or expansion, treat this as a signal for high-density delivery (3x the previous text depth). Do not merely rearrange sections; supplement with workflow examples, CLI patterns, anti-pattern logic, and installation/config pitfalls.

• Visual Anchor: Every technical info card must anchor on at least one high-quality visual element (e.g., product interface, architecture diagram, or CLI capture) from the source repository, solidified locally in docs/assets/images/ to avoid hotlink degradation.

• For mobile-first legibility (390px/720px), apply the 1.2x scale-up rule for all sub-text (meta, caption, badge, route labels) and ensure no inline font-size: < 11.2px exists. When the user explicitly says "字号放大1.2x", treat it as a global typography pass — multiply ALL font-size declarations by 1.2 at the CSS variable definition level, not just body text.

• Structural fix principle: when the user says "不是改颜色" or "not color patching", the fix must be structural (remove padding, box-shadow, unneeded elements) rather than overriding colors. This applies to bottom "black shelf" artifacts — remove the box-shadow causing the shadow and/or make body background match card background, do not paint over the dark color.

• Bottom black area pattern: a visible dark strip at the page bottom is typically caused by body background (#0b0f0d dark) showing through when .page doesn't fill the viewport. Fix structurally: (1) change body{background} from --bg to --card, (2) remove .card box-shadow that creates a visual "shelf" at the bottom, (3) only add min-height as a last resort.

• Verification failure pitfall — visual model misidentification (2026-06-07)：当用户说"有吗/没看到/证明给我"时，视觉分析模型可能误判：它会把 ENGINEERING section 里的 skill cards 布局误认为旧的 prob-grid 2×2 区域，或把页面其他 card 布局误认成目标区域。正确验证顺序是：

  1. 必须先 curl -s https://raw.githubusercontent.com/ccwq/infocard-pub/<sha>/docs/<slug>.html | grep "目标字符串" —— 源码验证优先于一切
  2. GitHub Pages CDN 更新后（延迟 30-120s）再用 browser_vision 截图
  3. 如果源码确认已改但视觉模型说"还有"，判定为误判，不重做 不依赖"截图里看起来如何"来判断代码是否正确——源码对比才是最终依据。

• Post-rebuild data completeness pitfall (2026-06-10)：rebuild 过程中最常见的错误不是换色，而是信息在重建时被遗漏或排序被打乱。典型场景：12 个样本卡重建后，其中一张的日期排序不对（视觉模型在截图里发现 2021-06-15 排在了 2022 年的条目后面）。防范方法：rebuild 完成后，用源码级检查（grep/count ODI编号/日期/关键字符串）确认所有原始数据都在位，再用 browser_vision 确认视觉顺序与预期一致。不要在只有截图验收的情况下宣布 rebuild 完成。

• Chronological ordering pitfall (2026-06-10)：当 rebuild 涉及按时间排列的样本/事件列表时，视觉 grid 顺序必须与时间顺序严格对应——不能按"车型"或"年款"分组后再按时间排，而要把所有条目放在一起统一按时间升序排后再切 grid 行。检查方法：rebuild 后 提取所有关键标识，排序后确认顺序符合预期。

Content handling rules

• Preserve factual scope; do not silently drop sections.

• If you compress, do so only with explicit user agreement.

• If a section is weak or bug-prone, prefer structural replacement over piecemeal patching.

• If the user wants a body module removed but not forgotten, relocate its key data into header meta pills or stats first, then delete the redundant block.

• For header compacting requests, reduce the meta block's wrapper spacing structurally so the pills sit closer to the viewport edge.

• For repository cards, keep repo facts and workflow details separate from opinionated analysis.

• For technical-analysis cards, keep evidence and interpretation separate.

• For X / social-post infocards, prefer high-density expansion over thin summaries: include author, date, engagement, core thesis, notable examples, and a clear take on why it matters.

• If the user says a card is "rough" or asks to "expand" / "add data", preserve the chapter skeleton but make the content richer, denser, and more explanatory instead of stopping at a thin summary.

• If a social post includes an image, treat the image as first-class content: analyze it, describe the visible UI/details, and keep the image embedded in the card when publishing.

• See references/x-post-card-playbook.md for the extraction and density workflow learned from this session.

• references/2026-06-10-toyota-cruise-rebuild-and-mcp-forge-for-investigation.md — 调查稿 mcp-forge 重建案例：12个样本完整保留、时间排序验证、NHTSA API 绕过、存量卡 rebuild 索引判断。

• references/2026-07-08-hardblue-from-scratch-rebuild-lesson.md — hardblue vs darkblue rebuild 区别：两种主题的 CSS 骨架完整对照。2026-07-08 session 教训：hardblue 重建必须从 theme/hardblue.html 完整读取 CSS 后从零构建，不能在旧布局上打补丁。

• references/rebuild-vs-expansion.md for the strict rebuild/expand distinction and verification rules.

• See references/2026-06-03-neo-mirai-skillopt-mobile-repair.md for the session pattern: source image selection, local asset solidification, exact image count, and the mobile stats/header recovery sequence.

• references/codegraph-benchmark-grid-pattern.md for the pattern: per-language performance numbers → grid2 with .item list, NOT <table>. Table overflows at 390px mobile viewport.

Recommended workflow

1. Classify the infocard type (open-source repo vs technical analysis).
2. Grill the user for up to 3 rounds (only if request is underspecified).
3. Freeze chapter skeleton and visual style.
4. Build the HTML/CSS from scratch (not patch the old layout).
5. If publishing, handle git push conflicts via:

   git fetch origin main && git rebase origin/main
   # if conflict in _index.yaml: rebuild index, git add, GIT_EDITOR=true git rebase --continue
   

6. Verify rendered content on desktop and mobile via --browser flag.
7. Verify the live public URL is reachable (HTTP 200).
8. Confirm worktree is clean.

Git conflict pattern (infocard-pub specific)

When pushing to infocard-pub and the remote has new commits (common because index.yml workflow auto-commits _index.yaml):

git fetch origin main && git rebase origin/main
# if _index.yaml conflicts:
python scripts/rebuild_index.py && git add _index.yaml && GIT_EDITOR=true git rebase --continue
git push

Do not use --no-rebase or merge — rebase keeps history clean. GIT_EDITOR=true skips the editor prompt during rebase continue.

Rebuild checklist

• title and subtitle match the subject
• the card reads dense but not cramped
• metadata blocks are visually balanced
• section titles are consistent
• no legacy layout artifacts remain
• all source identifiers present in rebuilt HTML (e.g. all 12 ODI numbers, all original dates, all key strings — grep before declaring done)
• chronological order verified if the card contains ordered samples/cases (extract all date/identifier strings and sort to confirm)
• mobile 390px view is checked
• public deployment is verified if applicable

Good defaults

When the user does not specify otherwise:

• prefer high-density over airy
• prefer explicit sectioning over narrative blur
• prefer structural rebuild over visual patching
• prefer exact verification over “looks okay”
• preserve the user’s requested chapter order and UI language

Final reminder

This skill exists to stop a common failure mode: “I added content, therefore I rebuilt.”

Rebuild: full write_file, never patch

When "重建" is triggered, always use write_file to produce the complete HTML, never patch. patch modifies structural indentation and nesting unpredictably on large HTML files, causing layout corruption. Confirmed in archify darkblue rebuild (2026-07-10): a targeted patch disrupted the twin-image hero section indentation, requiring full HTML rewrite to fix.

Correct rebuild workflow:

1. Collect data + images in parallel (git clone, GitHub API, copy assets)
2. write_file the complete HTML from scratch (not patch)
3. write_file meta.yaml
4. npm run build && git add && commit && push
5. HTTP verification
6. git rm old card (docs/.html + .meta.yaml)
7. commit deletion + push
8. Wiki sync

Rebuild: darkblue theme — full CSS skeleton required

When the user says "重建" for a darkblue-style card (e.g. last30days-skill, harness-self-improv), do NOT patch the old layout. Write the complete HTML from scratch using the full darkblue CSS system.

Darkblue CSS system (copied verbatim from theme/darkblue.html):

:root{
  --bg:#0c1020; --bg-2:#11162a; --panel:#171c2b; --panel-2:#0f1424;
  --ink:#eef4ff; --muted:#a8b7df; --line:rgba(255,255,255,.12);
  --cyan:#58c3ff; --blue:#4a78ff; --green:#2db36a; --yellow:#f4c84c; --purple:#8459ff;
  --shadow:0 18px 42px rgba(0,0,0,.34);
}
/* Hero: .hero / .hero-copy / .kicker / .badge-row / .badge / .badge.blue|green|purple|hot / .alert / .flow */
.hero{display:grid;grid-template-columns:minmax(0,1.08fr) minmax(280px,.92fr);gap:14px}
.hero-copy{min-width:0;display:grid;gap:10px;:start;:  }

{: / ui-monospace,monospace;:.;:uppercase;:(--cyan);:}
{:(,,);:;:-.;:  ;:}
{:(--panel);: solid (--line);:;:}

,,{:grid;:}
{:(,(,fr))}
{:(,(,fr))}
{: solid (--line);:(--panel-);:;:;:grid;:}

{:;:collapse;:;:;:hidden}
 {: ;:(--bg-);: solid (--line);;: / ui-monospace,monospace;:.;:uppercase;:(--muted)}
 {: ;: solid (--line);:(--ink);:;:;:top}

{:(--panel);: solid (--line);:;: ;:grid;:fr auto;:;:center}

(max-width:760px){
  {:fr}
  ,,{:fr}
  {:fr}
}

Do NOT use the old panel+grid3+wide hybrid layout for darkblue cards. Use section+grid-N throughout.

Support files

• references/infocard-content-insertion-position.md — 内容扩充时的插入位置规范：默认插入"前面"（step-grid 后 PAGE 01 前），不插 footer；PAGE 编号从 05 而非 01 开始；日期更新规则。2026-07-08 用户明确纠正：内容应插前面而非 footer。
• references/infocard-pub-git-stash-recovery.md — infocard-pub 仓库 git stash/pull/rebase 混乱状态的恢复步骤：先 abort rebase → checkout -- . → clean untracked → pull ff → 重新 patch。2026-07-08 本次 session 教训：修改已发布卡不需要 stash，直接 pull 后改 HTML 再 push。
• references/github-repo-readme-extraction-pattern.md — GitHub README 多段提取模式：分片提取大 README（>10K 字符）、知识卡章节模板、meta.yaml 字段规范、updated 字段防 CI verify 失败模式。
• references/2026-06-03-orphan-card-index-entry-handling.md — 孤儿索引条目诊断与处理流程：页面 404 时先确认文件是否存在，再判断修图片还是清索引，不要误判。
• references/2026-06-03-cheatsheet-template-body-lock-bug.md — cheatsheet-generate 输出 HTML 的 width:389px body 锁定 bug 检测、根因、修复方法。凡是用 cheatsheet 源文件生成的 infocard 必须重写全套 CSS，不能只修 body 宽度。
• references/2026-06-03-infocard-pub-rebuild-optimization.md That is not a rebuild.