rrwrite-assemble-manuscript

name: rrwrite-assemble-manuscript description: Assembles complete manuscript from individual section files in journal-specified order arguments:

name: target_dir description: Directory containing manuscript sections default: manuscript
name: validate description: Validate word counts against journal limits default: true allowed-tools:

Manuscript Assembly Protocol

Assembles a complete, reproducible manuscript from individual section files. Concatenates sections in journal-specified order, adds metadata, validates word counts, and generates assembly manifest.

Overview

This skill should be run AFTER all sections are drafted and BEFORE critique. It creates a single manuscript.md file from component sections that:

Is properly ordered according to journal requirements
Includes complete metadata (title, authors, journal, word count)
Is reproducible (manifest tracks what was assembled and when)
Is validated against journal word limits

Phase 1: Pre-Assembly Validation

1.1 Check Workflow State

# Verify state file exists
STATE_FILE="{target_dir}/.rrwrite/state.json"

if [ ! -f "$STATE_FILE" ]; then
  echo "❌ Error: No workflow state found in {target_dir}"
  echo "   Run /rrwrite-plan-manuscript first"
  exit 1
fi

echo "✓ Workflow state found"

1.2 Check Drafting Status

import json
from pathlib import Path

# Load state
state_file = Path("{target_dir}") / ".rrwrite" / "state.json"
with open(state_file) as f:
    state = json.load(f)

# Check drafting status
drafting = state['workflow_status']['drafting']
completed = drafting['completed_sections']
total = drafting['total_sections']

print(f"Drafting progress: {completed}/{total} sections completed")

if completed == 0:
    print("❌ Error: No sections have been drafted yet")
    print("   Run /rrwrite-draft-section to draft sections first")
    exit(1)

if completed < total:
    print(f"⚠ Warning: Only {completed}/{total} sections completed")
    print(f"   Missing sections may cause incomplete manuscript")

    # Ask user if they want to proceed
    response = input("Proceed with partial manuscript? (y/n): ")
    if response.lower() != 'y':
        print("Assembly cancelled")
        exit(0)

1.3 Identify Available Sections

# List all .md files in target directory (excluding special files)
echo "\nAvailable sections:"
find "{target_dir}" -maxdepth 1 -name "*.md" \
  ! -name "outline.md" \
  ! -name "repository_analysis.md" \
  ! -name "literature.md" \
  ! -name "journal_assessment.md" \
  ! -name "author_guidelines.md" \
  ! -name "critique.md" \
  ! -name "manuscript.md" \
  -exec basename {{}} \; | sort

Expected sections (typical):

abstract.md
introduction.md
methods.md (or materials_and_methods.md, experimental_procedures.md)
results.md
discussion.md
conclusion.md (optional)
data_availability.md (or availability.md)
code_availability.md (optional)
acknowledgements.md (optional)
funding.md (optional)

Phase 2: Run Assembly Script

2.1 Execute Assembly

echo "\n{'='*60}"
echo "Assembling Manuscript"
echo "{'='*60}\n"

# Run assembly script
python scripts/rrwrite-assemble-manuscript.py \
  --target-dir "{target_dir}" \
  --validate

The script will:

Load journal guidelines from assessment (if available)
Determine correct section order for the journal
Find and read all section files
Concatenate sections in correct order
Add manuscript header with metadata
Calculate total word count
Generate assembly manifest
Validate word counts against journal limits
Save complete manuscript to {target_dir}/manuscript.md

2.2 Review Assembly Output

The script outputs:

Section order used
Which sections were found/included
Which sections are missing
Word count per section
Total word count
Validation warnings (if any)

Example output:

Assembling manuscript for: Bioinformatics
Target directory: manuscript/repo_v1

Section order (11 sections):
  1. abstract
  2. introduction
  3. methods
  4. results
  5. discussion
  6. conclusion
  7. data_availability
  8. acknowledgements
  9. funding
  10. references

✓ Found: abstract (abstract.md)
  Word count: 247

✓ Found: introduction (introduction.md)
  Word count: 1,423

✓ Found: methods (methods.md)
  Word count: 2,156

✓ Found: results (results.md)
  Word count: 1,876

✓ Found: discussion (discussion.md)
  Word count: 1,102

⚠ Missing: conclusion

✓ Found: data_availability (availability.md)
  Word count: 127

⚠ Missing: acknowledgements

⚠ Missing: funding

⚠ Missing: references

============================================================
✓ Manuscript assembled successfully!
============================================================

Output: manuscript/repo_v1/manuscript.md
Total word count: 6,931 words
Sections included: 6
Sections missing: 4

Manifest saved: manuscript/repo_v1/assembly_manifest.json

Phase 3: Validate Assembly

3.1 Check Manuscript File

# Verify manuscript.md was created
MANUSCRIPT_FILE="{target_dir}/manuscript.md"

if [ ! -f "$MANUSCRIPT_FILE" ]; then
  echo "❌ Error: Manuscript file was not created"
  exit 1
fi

echo "✓ Manuscript file created: $MANUSCRIPT_FILE"

# Show file size
FILE_SIZE=$(wc -c < "$MANUSCRIPT_FILE")
echo "  File size: $FILE_SIZE bytes"

# Show line count
LINE_COUNT=$(wc -l < "$MANUSCRIPT_FILE")
echo "  Line count: $LINE_COUNT lines"

3.2 Review Word Count Validation

If journal guidelines are available, the script validates word counts:

Example validation output:

============================================================
Word Count Validation
============================================================

✓ Total word count within limits: 6,931 words (3000-7000)
✓ abstract: 247 words (within 150-250)
✓ introduction: 1,423 words (within 500-1500)
❌ methods: 2,156 words > 2000 (maximum)
✓ results: 1,876 words (within 1000-2000)
✓ discussion: 1,102 words (within 500-1500)
✓ data_availability: 127 words (within 50-150)

Action on violations:

❌ (exceeds maximum): Section must be edited down before submission
⚠ (below minimum): Consider expanding section
✓ (within limits): No action needed

3.3 Review Assembly Manifest

# Display manifest
echo "\nAssembly Manifest:"
cat "{target_dir}/assembly_manifest.json" | jq '.'

Manifest contains:

{
  "assembled_at": "2026-02-06T15:30:45.123456",
  "target_journal": "bioinformatics",
  "sections_included": [
    {
      "name": "abstract",
      "file": "abstract.md",
      "word_count": 247
    },
    {
      "name": "introduction",
      "file": "introduction.md",
      "word_count": 1423
    }
    // ... more sections
  ],
  "sections_missing": [
    "conclusion",
    "acknowledgements",
    "funding",
    "references"
  ],
  "total_word_count": 6931,
  "section_word_counts": {
    "abstract": 247,
    "introduction": 1423,
    "methods": 2156,
    "results": 1876,
    "discussion": 1102,
    "data_availability": 127
  },
  "validation_warnings": [
    "Required section missing: references"
  ]
}

Phase 4: Handle Warnings and Errors

4.1 Missing Required Sections

If required sections are missing:

# Check for required section warnings
WARNINGS=$(cat "{target_dir}/assembly_manifest.json" | jq -r '.validation_warnings[]')

if [ -n "$WARNINGS" ]; then
  echo "\n⚠ Required sections missing:"
  echo "$WARNINGS"

  echo "\nAction required:"
  echo "  1. Draft missing sections using /rrwrite-draft-section"
  echo "  2. Re-run assembly after drafting"
  echo "  3. Or proceed with partial manuscript (not recommended)"
fi

4.2 Word Count Violations

If word counts exceed limits:

echo "\n❌ Word count violations detected"
echo "  methods: 2,156 words > 2,000 (maximum)"
echo "\nAction required:"
echo "  1. Edit {target_dir}/methods.md to reduce length"
echo "  2. Re-run assembly: /rrwrite-assemble-manuscript"
echo "  3. Consider moving details to Supplementary Materials"

4.3 Section Order Issues

If sections are in non-standard order:

# The assembler automatically reorders sections based on journal guidelines
# But inform user if original files were in different order

echo "\n✓ Sections reordered according to journal requirements"
echo "  Original order: (from file timestamps)"
echo "  Final order: (from journal guidelines)"
echo "\nNo action needed - assembly handles reordering automatically"

Phase 5: Update Workflow State

5.1 Mark Assembly Complete

import sys
from pathlib import Path
sys.path.insert(0, str(Path('scripts').resolve()))
from rrwrite_state_manager import StateManager

manager = StateManager(output_dir="{target_dir}")

# Read manifest for statistics
import json
manifest_file = Path("{target_dir}") / "assembly_manifest.json"
with open(manifest_file) as f:
    manifest = json.load(f)

# Update assembly stage
manager.update_workflow_stage(
    "assembly",
    status="completed",
    file="{target_dir}/manuscript.md",
    manifest_file="{target_dir}/assembly_manifest.json",
    sections_included=len(manifest['sections_included']),
    sections_missing=len(manifest['sections_missing']),
    total_word_count=manifest['total_word_count'],
    validation_warnings=len(manifest.get('validation_warnings', []))
)

# Update main files tracking
manager.state["files"]["final_manuscript"] = "{target_dir}/manuscript.md"
manager.state["metadata"]["total_word_count"] = manifest['total_word_count']
manager._save_state()

print("✓ Workflow state updated")

Phase 6: Display Assembly Summary

6.1 Generate Summary Report

echo "\n{'='*60}"
echo "Assembly Complete"
echo "{'='*60}\n"

echo "Manuscript: {target_dir}/manuscript.md"
echo "Manifest: {target_dir}/assembly_manifest.json"

# Load manifest for summary
TOTAL_WORDS=$(cat "{target_dir}/assembly_manifest.json" | jq -r '.total_word_count')
SECTIONS_INCLUDED=$(cat "{target_dir}/assembly_manifest.json" | jq -r '.sections_included | length')
SECTIONS_MISSING=$(cat "{target_dir}/assembly_manifest.json" | jq -r '.sections_missing | length')

echo "\nStatistics:"
echo "  Total word count: $TOTAL_WORDS words"
echo "  Sections included: $SECTIONS_INCLUDED"
echo "  Sections missing: $SECTIONS_MISSING"

# Journal info
JOURNAL=$(cat "{target_dir}/assembly_manifest.json" | jq -r '.target_journal')
echo "  Target journal: $JOURNAL"

6.2 Next Steps Guidance

echo "\nNext Steps:"

if [ $SECTIONS_MISSING -gt 0 ]; then
  echo "  1. ⚠ Draft missing sections (if required)"
  echo "  2. Re-run assembly: /rrwrite-assemble-manuscript"
  echo "  3. Run critique: /rrwrite-critique-manuscript"
else
  echo "  1. ✓ All sections included"
  echo "  2. Run critique: /rrwrite-critique-manuscript"
  echo "  3. Review critique feedback"
  echo "  4. Make final edits"
  echo "  5. Re-assemble if sections were edited"
fi

echo "\nReproducibility:"
echo "  To reassemble manuscript: /rrwrite-assemble-manuscript --target-dir {target_dir}"
echo "  Manifest tracks all assembly details for reproducibility"

Phase 7: Verify Reproducibility

7.1 Test Reassembly

To verify reproducibility, the manuscript can be reassembled at any time:

# Reassemble (should produce identical output)
python scripts/rrwrite-assemble-manuscript.py \
  --target-dir "{target_dir}" \
  --output "{target_dir}/manuscript_v2.md"

# Compare outputs
diff "{target_dir}/manuscript.md" "{target_dir}/manuscript_v2.md"

# If no diff output, assembly is reproducible
# (timestamps will differ, but content should be identical)

7.2 Track Assembly History

Each assembly creates a new manifest with timestamp:

# Rename manifests to track history
mv "{target_dir}/assembly_manifest.json" \
   "{target_dir}/assembly_manifest_$(date +%Y%m%d_%H%M%S).json"

# Keep latest as assembly_manifest.json for tools
cp "{target_dir}/assembly_manifest_$(date +%Y%m%d_%H%M%S).json" \
   "{target_dir}/assembly_manifest.json"

Output Files

Primary Outputs

{target_dir}/manuscript.md
- Complete assembled manuscript
- All sections in correct order
- Metadata header
- Assembly manifest as HTML comment at end
{target_dir}/assembly_manifest.json
- Assembly metadata
- Sections included/missing
- Word counts per section
- Validation warnings
- Timestamp for reproducibility

State Updates

{target_dir}/.rrwrite/state.json
- Assembly stage marked complete
- Manuscript file path recorded
- Total word count updated
- Validation warnings count tracked

Error Handling

Common Errors

Error: "No workflow state found"

Cause: Assembly run before planning
Solution: Run /rrwrite-plan-manuscript first

Error: "No sections have been drafted yet"

Cause: Assembly run before drafting
Solution: Draft sections with /rrwrite-draft-section

Error: "Manuscript file was not created"

Cause: Assembly script failed
Solution: Check script output for errors, verify Python dependencies

Warning: "Required section missing"

Cause: Journal-required section not drafted
Solution: Draft missing section or proceed with partial manuscript

Warning: "Word count exceeds limit"

Cause: Section too long for journal
Solution: Edit section to reduce length, or move content to Supplementary

Validation

Validate Assembly Structure

# Check manuscript has all expected components
grep -q "^# " "{target_dir}/manuscript.md" && echo "✓ Has title" || echo "❌ Missing title"
grep -q "Target Journal:" "{target_dir}/manuscript.md" && echo "✓ Has journal" || echo "❌ Missing journal"
grep -q "Total Word Count:" "{target_dir}/manuscript.md" && echo "✓ Has word count" || echo "❌ Missing word count"
grep -q "<!-- Section:" "{target_dir}/manuscript.md" && echo "✓ Has section markers" || echo "❌ Missing sections"
grep -q "<!-- Assembly Manifest" "{target_dir}/manuscript.md" && echo "✓ Has manifest" || echo "❌ Missing manifest"

Validate Manifest Structure

# Validate JSON
jq empty "{target_dir}/assembly_manifest.json" && echo "✓ Valid JSON" || echo "❌ Invalid JSON"

# Check required fields
jq -e '.assembled_at' "{target_dir}/assembly_manifest.json" > /dev/null && echo "✓ Has timestamp"
jq -e '.target_journal' "{target_dir}/assembly_manifest.json" > /dev/null && echo "✓ Has journal"
jq -e '.sections_included' "{target_dir}/assembly_manifest.json" > /dev/null && echo "✓ Has sections"
jq -e '.total_word_count' "{target_dir}/assembly_manifest.json" > /dev/null && echo "✓ Has word count"

Success Criteria

Assembly is successful when:

✅ manuscript.md file created with all available sections
✅ Sections in correct order per journal guidelines
✅ Metadata header includes title, authors, journal, word count
✅ Assembly manifest generated with complete metadata
✅ Workflow state updated with assembly completion
✅ Word count validation performed (if guidelines available)
✅ Assembly is reproducible (can be run multiple times with same output)

Notes

Idempotent: Assembly can be run multiple times safely
Reproducible: Manifest tracks exact state of assembly for reproducibility
Flexible: Works with partial manuscripts (missing optional sections)
Validated: Checks word counts against journal limits automatically
Ordered: Uses journal-specific section order from guidelines
Tracked: State manager records assembly completion and statistics