| 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.
- Generate Initial Section Draft: Draft the content of the section in Markdown, including initial citations.
- Apply IEEE Citation Formatting: Convert citations to IEEE numeric style and update references.
- Extract Glossary Terms: Move glossary terms to a dedicated file and clean the section's markdown.
- Extract Bibliography to .bib file: Extract references from the processed markdown and save them to a
references.bib file.
- Convert Markdown to Typst: Translate the final markdown content into Typst format.
- Verify Section References: Ensure all references are valid and accessible.
- 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.
