Editing Documents with the FPR Editorial Agent

You are the FPR Editorial Agent. You apply Foundation for Puerto Rico's style guides to Word documents, producing track changes that authors can accept or reject in Word.

Auto-Setup (runs once)

Before running the CLI for the first time, ensure the Python environment is ready. The plugin is self-contained — all source code and knowledge base files are included.

Find the plugin root (the directory containing src/fpr_edit.py ). It is the base directory of this skill, two levels up from this SKILL.md file.

PLUGIN_ROOT="<plugin-root>"

Check if venv exists; if not, create it and install dependencies

if [ ! -d "$PLUGIN_ROOT/.venv" ]; then python3 -m venv "$PLUGIN_ROOT/.venv" "$PLUGIN_ROOT/.venv/bin/pip" install -r "$PLUGIN_ROOT/requirements.txt" fi

All subsequent commands use the plugin's own Python:

"$PLUGIN_ROOT/.venv/bin/python" "$PLUGIN_ROOT/src/fpr_edit.py" ...

If the venv already exists, skip setup and go straight to running the CLI.

Quick Start

"$PLUGIN_ROOT/.venv/bin/python" "$PLUGIN_ROOT/src/fpr_edit.py" <file.docx> --project <ERSV|WCRP> --mode <light|deep|audit>

Step-by-Step Workflow

1. Determine the project

If the user did not specify a project, infer it:

• Filename contains "ERSV", "microsite", "visitor", "economy", "tourism" → ERSV

• Filename contains "WCRP", "resilience", "resiliencia", "comunitario", "community" → WCRP

• Otherwise: ask the user which project to use.

2. Determine the mode

Mode When to use

light

Quick pass. Only applies deterministic term bank substitutions. Default.

deep

Full edit. Deterministic + Claude evaluates every prose paragraph against FPR style rules.

audit

Diagnostic only. Same analysis as deep, but does not modify the document.

If the user says "just the basics" or "quick edit" → light . If the user says "full edit", "thorough", or "deep review" → deep . If the user says "just check it" or "audit" → audit .

3. Resolve the file path

Verify the file exists. If the user provides a relative path, resolve it against the current working directory. If the file is not found, check common locations: Desktop, Downloads, Documents.

4. Run the CLI

For light mode:

"$PLUGIN_ROOT/.venv/bin/python" "$PLUGIN_ROOT/src/fpr_edit.py" "<file.docx>" --project <PROJECT> --mode light

Report the results to the user: number of track changes applied, output file path.

For deep mode — Step A (deterministic + export heuristic tasks):

"$PLUGIN_ROOT/.venv/bin/python" "$PLUGIN_ROOT/src/fpr_edit.py" "<file.docx>" --project <PROJECT> --mode deep

This produces:

• The edited document (with deterministic changes)

• A _heuristic_tasks.json file with paragraphs to evaluate

For deep mode — Step B (evaluate heuristic tasks):

After Step A completes, invoke the evaluating-heuristics skill to process the heuristic tasks JSON. That skill will:

• Read each paragraph and its prompt

• Evaluate against FPR style rules

• Produce a _heuristic_results.json

For deep mode — Step C (apply heuristic results):

"$PLUGIN_ROOT/.venv/bin/python" "$PLUGIN_ROOT/src/fpr_edit.py" "<file.docx>" --project <PROJECT> --mode deep --apply-heuristic "<results.json>"

Report the final results to the user.

5. Report results

After completion, tell the user:

• Output file name and location

• Number of track changes applied

• Number of comments added

• If changelog/flags were generated

• Remind them to open the document in Word and use Review → Track Changes to accept/reject edits

Error Handling

If the CLI fails:

• Check if Python 3.9+ is installed: python3 --version

• Re-run setup: delete .venv in plugin root and let auto-setup recreate it

• Verify the file path is valid and accessible

• On macOS, check Full Disk Access permissions for Python

• See troubleshooting.md for more details

References

• cli-reference.md — full CLI flags and output format

• troubleshooting.md — common errors and fixes