thesis-section-crafting

name	thesis-section-crafting
description	Guide for creating a complete thesis section autonomously, from initial drafting to Typst formatting and reference management.

Thesis Section Crafting Skill - Instructions for Gemini CLI Agent

Your mission is to autonomously craft a complete thesis section from start to finish, following the project's academic and formatting standards. This skill orchestrates several sub-tasks, leveraging specialized scripts and adhering to the guidelines in thesis/WORKFLOWS.md.

Workflow Overview:

The process is broken down into the following sequential steps. You MUST complete them in order. If any step fails, report the failure and stop, allowing the user to intervene.

1. Generate Initial Section Draft: Draft the content of the section in Markdown, including initial citations.
2. Apply IEEE Citation Formatting: Convert citations to IEEE numeric style and update references.
3. Extract Glossary Terms: Move glossary terms to a dedicated file and clean the section's markdown.
4. Extract Bibliography to .bib file: Extract references from the processed markdown and save them to a references.bib file.
5. Convert Markdown to Typst: Translate the final markdown content into Typst format.
6. Verify Section References: Ensure all references are valid and accessible.
7. Include Section in Chapter: Add the newly created section to its parent chapter's Typst file.

---

Step 1: Generate Initial Section Draft

Goal: Produce an initial Markdown draft of the requested thesis section, incorporating academic claims and citations (APA 7th edition style for now, to be converted later).

Input:

• <SECTION_ID>: The numeric identifier of the section (e.g., 1.1, 3.7).
• The current thesis/THESIS_OUTLINE.md for section details (title, word count, outline bullets).
• thesis/thesis_templates/SECTION_TEMPLATE.md for structure.
• Project context documents for content guidance.

Action: Call the create_section_draft.ts script. This script acts as an intermediary, setting up the context for you (the LLM agent) to generate the actual content.

Command: npx tsx scripts/create_section_draft.ts <SECTION_ID>

• The script determines <CHAPTER_NAME> from the <SECTION_ID> based on thesis/THESIS_OUTLINE.md. For example, for SECTION_ID "1.1", <CHAPTER_NAME> would be "01_introduction".
• The script will then construct a prompt and you (the agent) will be expected to fill in the content of the section according to the prompt generated by the script.
• The output will be saved to thesis/typst/chapters/<chapter_name>/sections/<section_id_snake_case>/content.md.

Verification:

• Confirm content.md exists in the expected directory.
• Perform a quick review of content.md for basic content presence (not empty, looks like a draft).

---

Step 2: Apply IEEE Citation Formatting

Goal: Convert the Markdown draft's citations to IEEE numeric format and restructure the references section.

Input:

• The content.md file generated in Step 1.

Action: Call the ieee_cite_processor.ts script.

Command: npx tsx scripts/ieee_cite_processor.ts <path_to_content.md>

• <path_to_content.md> will be thesis/typst/chapters/<chapter_name>/sections/<section_id_snake_case>/content.md.
• The script will rename the original content.md to content_ieee.md upon completion.

Verification:

• Confirm content_ieee.md exists and content.md has been removed.
• Visually inspect content_ieee.md to ensure citations are numeric (e.g., [1]) and the References section is properly formatted.

---

Step 3: Extract Glossary Terms

Goal: Move any defined glossary terms from the section's markdown to a separate glossary.md file and prepare the markdown for further processing.

Input:

• The content_ieee.md file from Step 2.

Action: Call the extract_glossary_terms.ts script.

Command: npx tsx scripts/extract_glossary_terms.ts <path_to_content_ieee.md>

• <path_to_content_ieee.md> will be thesis/typst/chapters/<chapter_name>/sections/<section_id_snake_case>/content_ieee.md.
• The script will append terms to glossary.md in the same directory and rename content_ieee.md to content_ieee_no_glossary.md.

Verification:

• Confirm content_ieee_no_glossary.md exists and content_ieee.md has been removed.
• Confirm glossary.md exists (if terms were extracted) and contains the correct terms.

---

Step 4: Extract Bibliography to .bib file

Goal: Extract the IEEE-formatted references from the processed markdown and save them to the section's references.bib file.

Input:

• The content_ieee_no_glossary.md file from Step 3.

Action: Call the extract_bibliography.ts script.

Command: npx tsx scripts/extract_bibliography.ts <path_to_content_ieee_no_glossary.md> <path_to_references.bib>

• <path_to_content_ieee_no_glossary.md> will be thesis/typst/chapters/<chapter_name>/sections/<section_id_snake_case>/content_ieee_no_glossary.md.
• <path_to_references.bib> will be thesis/typst/chapters/<chapter_name>/sections/<section_id_snake_case>/references.bib.

Verification:

• Confirm references.bib exists and contains BibTeX entries.
• Visually inspect references.bib for basic correctness.

---

Step 5: Convert Markdown to Typst

Goal: Transform the final processed Markdown content into the Typst format (content.typ).

Input:

• The content_ieee_no_glossary.md file from Step 3. (Note: The script reads this file, but the references.bib created in Step 4 is also crucial for Typst's bibliography)

Action: Call the markdown_to_typst_converter.ts script.

Command: npx tsx scripts/markdown_to_typst_converter.ts <path_to_content_ieee_no_glossary.md> <path_to_content.typ>

• <path_to_content_ieee_no_glossary.md> will be thesis/typst/chapters/<chapter_name>/sections/<section_id_snake_case>/content_ieee_no_glossary.md.
• <path_to_content.typ> will be thesis/typst/chapters/<chapter_name>/sections/<section_id_snake_case>/content.typ.

Verification:

• Confirm content.typ exists in the expected directory.
• Perform a quick review of content.typ for basic Typst formatting (e.g., headings with =, citations cite:).

---

Step 6: Verify Section References

Goal: Ensure all references within the section's references.bib file are valid and accessible.

Input:

• The section's references.bib file (thesis/typst/chapters/<chapter_name>/sections/<section_id_snake_case>/references.bib).

Action: Call the verify_references.ts tool.

Command: npx tsx .gemini/v1/cli-tools/ref-tools/verify-references.ts <path_to_references.bib>

• <path_to_references.bib> will be thesis/typst/chapters/<chapter_name>/sections/<section_id_snake_case>/references.bib.
• This will generate a validation report in Markdown in the same directory.

Verification:

• Read the generated *-validation-report-*.md file.
• If any ❌ Broken Link or ⚠️ Suspicious entries are found: You MUST inform the user and request guidance on how to fix them, as this requires external research or user input. Do not proceed until these are resolved.
• If all references are ✅ Verified, proceed to the next step.

---

Step 7: Include Section in Chapter

Goal: Integrate the newly created section's content.typ into its parent chapter's chapter.typ file.

Input:

• The section's content.typ file.
• The parent chapter's chapter.typ file (thesis/typst/chapters/<chapter_name>/chapter.typ).

Action: Call the include_section_in_chapter.ts script.

Command: npx tsx scripts/include_section_in_chapter.ts <path_to_chapter.typ> <section_id_snake_case>

• <path_to_chapter.typ> will be thesis/typst/chapters/<chapter_name>/chapter.typ.
• <section_id_snake_case> will be the snake-cased version of the section ID (e.g., 1_1_background).
• The script will add the line #include "sections/<section_id_snake_case>/content.typ" to the chapter.typ file if it's not already present.

Verification:

• Read <path_to_chapter.typ> and confirm the #include statement for the new section is present.

---

Completion Criteria:

This skill is complete when all seven steps have been successfully executed and verified for the specified section.

Important Note on LLM Interaction (Step 1): When create_section_draft.ts is called, it will prompt you (the agent) to generate the content for the section. You MUST adhere to the instructions provided by that prompt, including sourcing, citation formatting (APA 7th), and adherence to the SECTION_TEMPLATE.md.