thesis-standardizer

Thesis Standardizer

Purpose

Default to one main job: turn a real program into a defensible undergraduate thesis.

Always work from evidence:

1. template rules
2. project facts
3. code/database/API/test evidence
4. chapter plan
5. prose
6. figures/tables
7. Word/PDF checks

Do not start from free prose unless the user explicitly asks for a rough draft and accepts missing evidence risk.

Non-Negotiable Completion Gate

This skill uses a Superpowers-style gate structure: rules are not reminders; they are executable stop conditions.

NO FINAL DOCX COMPLETION CLAIM WITHOUT FRESH AGGREGATE-GATE EVIDENCE

Before saying a thesis .docx is complete, acceptable, fixed, or ready:

1. Identify the final .docx, figure map, expected Visio OLE count, heading minimums, and required thesis length.
2. Run scripts/check_final_thesis_docx.ps1 on the current file, not a previous draft. For normal undergraduate system theses, use -MinContentUnits 12000 -MinCjkChars 10000 unless the school template says otherwise.
3. Read the output and exit code.
4. If any gate fails, repair the document or report the exact failed gate. Do not call it done.
5. Only after the aggregate gate passes, report the verification evidence.

Red flags that mean stop and run the gate:

• "The table rules are already in the skill."
• "The document looks fine in Word."
• "Three-line tables passed, so continuation is probably fine."
• "The previous demo passed."
• "Only a small edit was made."
• "Visio/OLE is unrelated to this table change."

Mainline: Program To Thesis

For a project/repo/system source, run this route:

1. If a school .docx template exists, extract it: scripts/extract_docx_template_profile.py <template.docx> --out paper-context/template-extract Then build the component-oriented replication plan: scripts/build_thesis_structure_plan.py --template-profile paper-context/template-extract/template-profile.json --spec thesis-ai-standard/templates/thesis-ai-spec.yaml --out paper-context/template-extract/thesis-structure-plan.yaml Read references/template-replication-workflow.md before drafting or final formatting when a template is present.
2. Initialize/check the thesis workspace: scripts/init_thesis_workspace.py <target-dir>
3. Build project evidence: scripts/build_project_evidence.py <project-dir> --out paper-context/evidence
4. Fill or update: thesis-ai-standard/templates/standard-profile.yaml thesis-ai-standard/templates/thesis-ai-spec.yaml thesis-ai-standard/templates/figure-registry.yaml
5. Build the figure/screenshot plan before drafting Chapter 3-6: scripts/build_figure_plan.py thesis-ai-standard/templates/thesis-ai-spec.yaml --out paper-context/figure-plan Merge planned figures into figure-registry.yaml or keep the fragment as the drafting checklist.
6. Draft by chapter using the chapter map below.
7. For Chapter 4, build the database-design asset set before drafting database/data-object sections: scripts/build_chapter4_database_assets.py <database-model.yaml> --out paper-context/database-design If no business database exists but the project has real structured configuration/data artifacts such as YAML, JSON, JSONL, Markdown registries, logs, or generated evidence files, create a clearly labeled data-object model from those artifacts and generate the same overview E-R, single-entity E-R, and three-line table assets. Do not call it a physical business database.
8. Generate required Visio diagrams, screenshot placeholders, and three-line tables only when the chapter needs them. When producing the final .docx, embed structural .vsdx figures as Visio OLE objects when OfficeCLI or Word automation is available; the .png export is only the preview thumbnail. Check exported preview aspect ratios before embedding, and use aspect-fit OLE sizing instead of a universal fixed rectangle.
9. Run final checks: scripts/check_thesis_workspace.py <workspace> If a final .docx is produced, also run scripts/check_final_thesis_docx.ps1 <paper.docx> -FigureMap <visio-ole-figure-map.json> -ExpectedVisioOle <count> -MinContentUnits 12000 -MinCjkChars 10000 -RequireContinuationCaption. When a template profile exists, add -TemplateProfile <template-profile.json>. Do not mark the document complete if this aggregate gate fails.

Read references/thesis-module-workflow.md when planning or executing the full route.

Skill Integrity

After editing this skill, run scripts/check_skill_integrity.py before claiming the skill is ready. It checks frontmatter, referenced scripts/ and references/ files, aggregate gate wiring, and variant workflow reachability.

Variant Generation

When the user asks for multiple thesis candidates or wants to compare optimization strategies, use references/variant-generation-workflow.md.

Default to three isolated variants:

1. template-first: prioritize school-template reproduction and template replication gates.
2. figure-enhanced: prioritize Chapter 3-6 figure planning, Visio sources, OLE embedding, and figure-map gates.
3. narrative-enhanced: prioritize thesis voice, chapter coherence, and thesis-length prose quality.

Use scripts/generate_thesis_variants.py to create the variant matrix and optional isolated runs, then use scripts/compare_thesis_variants.py to produce the comparison summary. A winning or merged final .docx still needs a fresh scripts/check_final_thesis_docx.ps1 run; variant gate evidence is not transferable after merging or editing.

Chapter Map

• Chapter 1, introduction: background, significance, research status, research content, thesis structure. This is citation-heavy.
• Chapter 2, related technologies: explain each technology and how this system uses it. This is citation-heavy.
• Chapter 3, system analysis: feasibility, roles, requirements, non-functional requirements, use-case diagram, core business flowchart, requirement/function decomposition figure when evidence supports them.
• Chapter 4, system design: function architecture diagram, overall architecture diagram, technical/deployment architecture diagram when supported, E-R overview, single-entity E-R diagrams, database/data-object three-line tables, and design rationale.
• Chapter 5, system implementation: key module implementation, implementation flowcharts, real program screenshots for login/entry, homepage, and core functions; use needs_user_screenshot placeholders when real screenshots are missing. This chapter is not the testing chapter.
• Chapter 6, system testing: test environment, test methods, test cases, logs/reports, test result screenshots if real evidence exists, and result tables. Do not put normal program-function screenshots here. Do not create a separate Chapter 7 by default; when conclusion content is needed, place a concise completed-work, limitations, and future-work section at the end of Chapter 6. Create standalone Chapter 7 only when the school template or user explicitly requires it.

Chapters 1-3 are the main citation area. Do not force citations into implementation or test claims unless the claim genuinely needs literature support. Before drafting or expanding thesis prose, read references/thesis-voice-and-style.md. Evidence files are for working memory and verification; the final thesis body must describe the system directly.

Diagram And Table Routing

• Figure/screenshot plan: references/figure-and-screenshot-plan.md Run build_figure_plan.py before drafting Chapter 3-6. A normal system thesis should plan many evidence-backed figures, not only one use-case diagram and one function diagram.
• Word delivery with editable Visio: read references/docx-production-rules.md For generated structural .vsdx figures, run scripts/check_figure_preview_aspects.py, then prefer scripts/embed_visio_ole_with_officecli.py --fit-preview-aspect --max-width 14cm --max-height 18cm and verify the final .docx with both scripts/check_docx_visio_ole.py and scripts/check_docx_duplicate_figure_previews.py. A PNG preview in Word is not an editable Visio diagram, and a final Word figure block must not contain both a Visio OLE object and the old static PNG preview.
• Template replication: read references/template-replication-workflow.md When a school/template .docx exists, do not rely only on visual similarity. Extract template-profile.json, build thesis-structure-plan.yaml, and verify final output with scripts/check_docx_component_order.py, scripts/check_docx_style_profile.py, scripts/check_docx_page_model.py, scripts/check_docx_caption_numbering.py, and scripts/report_template_replication_diff.py.
• Hard DOCX gates: read references/hard-gate-rule-catalog.md A final thesis .docx should pass component completeness, citation closure, reference hyperlink, caption closure, and structural hygiene checks. Use -SkipHardGateChecks only for rough internal drafts, never for delivery claims.
• Use-case diagram: references/visio-use-case-workflow.md Run layout_use_case_diagram.py, check_use_case_layout.py, generate_visio_use_case_diagram.ps1.
• Function architecture diagram: references/visio-function-architecture-workflow.md Run layout_function_architecture_diagram.py, check_function_architecture_layout.py, generate_visio_function_architecture_diagram.ps1.
• E-R diagram: references/visio-diagram-workflow.md Run layout_er_diagram.py, check_er_layout.py, generate_visio_er_diagram.ps1.
• Chapter 4 database assets: references/chapter-4-database-workflow.md Run build_chapter4_database_assets.py, then render the overview and single-entity E-R JSON with the ER Visio route.
• Flowchart: references/visio-flowchart-workflow.md Run layout_flowchart_diagram.py, check_flowchart_layout.py, generate_visio_flowchart_diagram.ps1.
• Three-line and continuation tables: read references/docx-production-rules.md, then use scripts/create_three_line_table.py. A Word Table Grid table is not a three-line table. For final DOCX output, run scripts/check_docx_table_continuations.ps1; if tables cross pages, require repeated header rows, disabled row splitting, and visible continuation captions when the school/template or user expects them.

Keep editable sources: .vsdx for Visio figures and script/Word source for final tables. For Word delivery, a PNG inserted into the body is only a preview image. A figure should not be called "Word-editable Visio" unless the .docx contains a Visio OLE object, verified with scripts/check_docx_visio_ole.py.

Hard Rules

• School and advisor rules override defaults.
• Never invent project functions, APIs, database fields, tests, screenshots, experiments, citations, DOI values, or school rules.
• If evidence is missing, list missing materials instead of pretending.
• Do not silently skip Chapter 4 database/data-object design. If schema/entity/migration/SQL evidence exists, generate overview E-R, single-entity E-R diagrams, and database three-line tables. If no business database evidence exists but the project has real structured configuration or evidence artifacts, generate a clearly labeled data-object E-R model and three-line tables from those artifacts. If neither exists, create an evidence gap before drafting Chapter 4.
• Do not merge implementation into Chapter 4 by default. For a normal system thesis, Chapter 4 is design, Chapter 5 is implementation, and Chapter 6 is testing. Do not create Chapter 7 unless the school template or user explicitly requires a standalone conclusion chapter.
• Do not under-plan figures for a normal system thesis. If fewer than 8 figures are planned across Chapters 3-6, explain the small scope or missing evidence.
• Never fabricate Chapter 5 program screenshots. Chapter 5 is the implementation chapter and should contain real running-program screenshots for implemented functions. If the app cannot be run or screenshots are not provided, create needs_user_screenshot entries in figure-registry.yaml and list them as evidence gaps.
• A three-line table means only top border, header-bottom border, and bottom border. No vertical borders, no internal grid lines, and no Word Table Grid styling. Verify final DOCX tables with scripts/check_docx_three_line_tables.py when a .docx is produced.
• Three-line table verification must fail on table-level borders and inherited insideH/insideV cell borders, not only obvious left/right grid lines.
• Cross-page tables must not be left to Word defaults. Mark the header row as repeated, disable row splitting across pages, and when continuation captions are required, add visible 续表 x.x / 表 x.x（续） captions. Verify with scripts/check_docx_table_continuations.ps1; do not rely on visual inspection alone.
• A final thesis .docx must pass the aggregate gate scripts/check_final_thesis_docx.ps1, which includes three-line table borders, continuation-table pagination, heading levels, thesis voice, Visio OLE embedding, duplicate-preview detection, figure aspect checks, document component/order checks, citation closure, reference hyperlink checks, caption closure, and DOCX structural hygiene. If the aggregate gate fails, fix the document or report it as blocked.
• Body reference markers such as [1] must be real Word internal hyperlinks that Ctrl+left-click to the matching reference entry bookmark, not plain text. For generated or repaired DOCX files, run scripts/apply_docx_reference_hyperlinks.py <paper.docx> and verify with scripts/check_docx_reference_hyperlinks.py <paper.docx>. Do not claim reference handling is complete from citation text closure alone.
• Citation markers embedded inside prose, for example 相关研究[1]表明, still need hyperlink and superscript repair; plain-text markers are not acceptable just because the citation number exists in the references.
• When a template profile is supplied, the aggregate gate must also run template style, page model, and replication-diff checks. Do not claim template reproduction from visual inspection alone.
• A normal undergraduate system-design thesis should be about 12000 Chinese-content units unless the school gives another target. Verify with scripts/check_docx_thesis_quality.py or the aggregate gate options -MinContentUnits 12000 -MinCjkChars 10000; do not deliver a 4000-word demo as if it were thesis-length.
• Final thesis prose must read like a student thesis, not an audit report or assistant work log. Keep source evidence in workspace files and reports, but do not put wording such as 证据, 当前材料, 根据源码, README, PRD, 不编造, 占位, or 待补 into the thesis body. Verify with scripts/check_docx_thesis_voice.py or the aggregate gate.
• If a final .docx changes after a successful gate run, the gate evidence is stale. Run scripts/check_final_thesis_docx.ps1 again before any completion claim.
• For final .docx delivery, do not represent structural Visio diagrams only as static PNGs unless OLE embedding is impossible and explicitly reported. Prefer scripts/embed_visio_ole_with_officecli.py --fit-preview-aspect, then verify with scripts/check_docx_visio_ole.py and scripts/check_docx_duplicate_figure_previews.py.
• A Visio o:OLEObject tag is insufficient by itself. check_docx_visio_ole.py must also see a non-external relationship target under word/embeddings/; missing payloads are delivery blockers.
• Do not force every Visio OLE object into one fixed display size such as 14cm x 8cm. Preserve the preview aspect ratio. If scripts/check_figure_preview_aspects.py reports an extreme flat/tall figure, re-layout or split the source diagram before final delivery.
• For generated flowchart .vsdx figures, do not rely on Visio automatic routing alone. Run layout_flowchart_diagram.py so each edge receives orthogonal route points, then run check_flowchart_layout.py and require connectorCrossings: 0 before rendering or embedding the figure.
• For generated E-R .vsdx figures, run check_er_layout.py after layout_er_diagram.py and require both overlapPairs: 0 and connectorCrossings: 0. If the overview E-R is crowded, put only entities and relationships in the overview and move attributes to single-entity E-R diagrams and three-line tables.
• Single-entity E-R diagrams should use dispersed boundary glue points rather than one common center point. Prefer short Chinese field labels from schema comments, stripping parenthetical implementation notes such as enum values or encryption details.
• Every figure/table/equation/screenshot must have a source file, export file when applicable, first mention, and status in figure-registry.yaml.
• Do not expose AI workflow language in thesis prose.
• For stable final .docx files, avoid whole-document markdown round trips unless the user accepts layout risk. Markdown-to-Word/Pandoc output must still pass check_docx_three_line_tables.py, check_docx_visio_ole.py, Office/OpenXML validation, and figure aspect checks before it can be treated as deliverable.

Minimal Reads

When thesis-ai-standard/ exists, read these first and stop unless more detail is needed:

1. thesis-ai-standard/templates/standard-profile.yaml
2. thesis-ai-standard/templates/thesis-ai-spec.yaml
3. thesis-ai-standard/templates/figure-registry.yaml
4. paper-context/evidence/, if present
5. paper-context/template-extract/template-rule-overrides.yaml, if present
6. paper-context/template-extract/template-profile.json, if present
7. paper-context/template-extract/thesis-structure-plan.yaml, if present
8. paper-context/database-design/, if present
9. paper-context/figure-plan/, if present

Use deeper reference files only for the active task.