Skip to main content

Process Documentation

Process documentation from: $ARGUMENTS

System Prompt​

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

  1. IMMEDIATELY execute - no questions, no explanations first
  2. ALWAYS show full output from script/tool execution
  3. ALWAYS provide summary after execution completes

DO NOT:

  • Say "I don't need to take action" - you ALWAYS execute when invoked
  • Ask for confirmation unless requires_confirmation: true in frontmatter
  • Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

Arguments​

$ARGUMENTS - Processing Configuration (optional)​

Specify files to process:

  • All files: No arguments - processes all files in NEW/
  • Dry run: "--dry-run" - preview changes without applying
  • Specific file: "--file 'filename.txt'"
  • With options: "--dry-run --file 'guide.txt'"

Default Behavior​

If no arguments:

  • Processes all .txt files in docs/original-research/NEW/
  • Converts to formatted markdown
  • Archives sources to BU/
  • Updates README.md
  • Commits and pushes changes

Purpose​

Automatically process new documentation files from docs/original-research/NEW/ directory through the complete 4-phase workflow.

Usage​

# Process all files in NEW/
/process-docs

# Preview changes without making them
/process-docs --dry-run

# Process specific file
/process-docs --file "filename.txt"

What It Does​

Automated 4-Phase Workflow:

  1. Conversion - Convert .txt files to formatted markdown
  2. Organization - Determine optimal placement in docs/ structure
  3. Archival - Move source files to BU/ directory
  4. Integration - Update README.md and commit changes

Examples​

Process All New Files​

/process-docs

Output:

Processing 2 file(s):
  ✅ The greatest Claude Code workflow.txt → claude-code-workflow.md
  ✅ Cursor Tutorial.txt → cursor-tutorial.md

Summary:
  - 2 files processed
  - 2 markdown files created
  - README.md updated
  - Changes committed and pushed

Preview Changes (Dry Run)​

/process-docs --dry-run

Output:

[DRY RUN MODE]

Would process:
  - The greatest Claude Code workflow.txt
    → docs/claude-code-workflow.md
    → Archive to BU/

No changes made.

Process Specific File​

/process-docs --file "The greatest Claude Code workflow.txt"

Command Implementation​

This command invokes the Python automation script:

import subprocess
from pathlib import Path

def process_docs(dry_run=False, file=None):
    repo_root = Path.cwd()
    script_path = repo_root / "scripts" / "process-new-docs.py"

    cmd = ["python3", str(script_path)]

    if dry_run:
        cmd.append("--dry-run")

    if file:
        cmd.extend(["--file", file])

    result = subprocess.run(cmd, capture_output=True, text=True)

    print(result.stdout)
    if result.returncode != 0:
        print(result.stderr)

    return result.returncode == 0

Prerequisites​

  • Python 3.7+
  • Git repository initialized
  • Repository structure matches claude-code-howtos layout

Error Handling​

File Not Found:

❌ Error: File 'nonexistent.txt' not found in NEW/ directory

Git Errors:

❌ Git commit failed: No changes staged

Conversion Errors:

⚠️  Warning: Could not extract title from file, using filename

Workflow Integration​

Manual Usage​

  1. Drop .txt files into docs/original-research/NEW/
  2. Run /process-docs
  3. Review changes
  4. Files automatically committed and pushed

Automated Usage (Git Hook)​

# Enable pre-commit hook
cp scripts/pre-commit-hook.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Hook automatically prompts to process NEW/ files before commit.

Cloud Automation (GitHub Actions)​

# See .github/workflows/process-docs.yml
# Automatically processes files when pushed to NEW/

Configuration​

Edit scripts/process-new-docs.py to customize:

  • Output directory: Change self.docs_dir
  • Archive directory: Change self.bu_dir
  • Commit message format: Modify commit_and_push() method
  • Markdown formatting: Edit _format_as_markdown() method

Logs​

Processing logs saved to:

logs/doc-processing.log

View recent activity:

tail -f logs/doc-processing.log
  • /export-dedup - Export and deduplicate current session
  • /git-sync - Synchronize git submodules
  • /analyze-session - Analyze session patterns

Best Practices​

✅ DO:

  • Use --dry-run first to preview changes
  • Check README.md after processing to add descriptions
  • Review generated markdown for formatting quality
  • Process files in small batches for easier review

❌ DON'T:

  • Process files with sensitive information
  • Mix multiple topics in one batch
  • Skip the dry-run for important documents
  • Forget to pull before processing in team environments

Troubleshooting​

Issue: "No files found in NEW/"​

Solution: Verify files are in docs/original-research/NEW/ with .txt extension

Issue: "Git push failed"​

Solution: Pull latest changes first: git pull origin main

Issue: "README.md not updated"​

Solution: Check README.md has "## Documentation" section header

Issue: "Markdown formatting poor"​

Solution: Edit the .txt source for better structure, then reprocess

Technical Details​

Script Location: scripts/process-new-docs.py (450 lines) Language: Python 3 Dependencies: Standard library only (no pip install required)

Processing Steps:

  1. Scan NEW/ directory for .txt files
  2. For each file:
    • Read content with encoding detection
    • Extract title and metadata
    • Format as markdown with proper headers
    • Create file in docs/
    • Update README.md with new entry
    • Move source to BU/
    • Git add, commit, push

Performance:

  • Small files (<100KB): <1 second
  • Large files (>1MB): 2-5 seconds
  • Batch processing: ~2 seconds per file

Examples in Practice​

Example 1: Process YouTube Transcript​

# 1. Download transcript to NEW/
# docs/original-research/NEW/Claude Code Tutorial.txt

# 2. Process
/process-docs

# Result:
# - docs/claude-code-tutorial.md created
# - README.md updated with new entry
# - Source moved to BU/
# - Committed: "docs: Add Claude Code Tutorial guide"

Example 2: Batch Process Multiple Files​

# NEW/ contains:
# - Guide 1.txt
# - Guide 2.txt
# - Guide 3.txt

/process-docs

# Result:
# All 3 files processed in sequence
# Single commit with all changes

Example 3: Test Before Processing​

# Preview what will happen
/process-docs --dry-run

# Output shows:
# - Which files will be processed
# - Generated filenames
# - Where files will be moved
# - No actual changes made

# If satisfied, run for real:
/process-docs

Future Enhancements​

  • AI-powered categorization - Auto-detect best docs/ subdirectory
  • Quality scoring - Rate markdown conversion quality
  • Duplicate detection - Check for similar existing guides
  • Batch editing - Process multiple files with unified settings
  • Web preview - Preview markdown rendering before commit

Changelog​

v1.0.0 (December 2024)

  • Initial release
  • Basic conversion, archival, README update, git commit
  • Dry-run mode for testing
  • Single file processing support
  • Comprehensive logging

Action Policy​

<default_behavior> This command processes documentation files. Proceeds with:

  • File scanning in NEW/
  • Markdown conversion
  • Archival to BU/
  • README update
  • Git commit (unless --dry-run)

Provides progress updates during execution. </default_behavior>

After execution, verify: - Files converted - Archives created - README updated - Git committed

Success Output​

When process-docs completes:

✅ COMMAND COMPLETE: /process-docs
Files Processed: <N>
Markdown Created: <N>
README Updated: Yes
Status: Committed

Completion Checklist​

Before marking complete:

  • Files scanned
  • Conversion done
  • Archives created
  • README updated
  • Git committed

Failure Indicators​

This command has FAILED if:

  • ❌ No files in NEW/
  • ❌ Conversion failed
  • ❌ Git commit failed
  • ❌ README not updated

When NOT to Use​

Do NOT use when:

  • Files not in NEW/
  • Binary files
  • Sensitive content

Anti-Patterns (Avoid)​

Anti-PatternProblemSolution
Skip --dry-runUnexpected changesPreview first
Large batchesHard to reviewProcess in small groups
Skip README checkMissing entriesVerify after processing

Principles​

This command embodies:

  • #3 Complete Execution - Full 4-phase workflow
  • #4 Idempotent - Safe to re-run
  • #6 Clear, Understandable - Clear progress

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Command Type: Automation Category: Documentation Author: Claude Code Last Updated: December 2024