# How to Resume a Broken cangjie-skill Pipeline from PIPELINESTATE.md

> Learn how to resume a broken cangjie-skill pipeline by editing PIPELINESTATE.md. Reset failed stages and restart your pipeline efficiently, skipping completed tasks.

- Repository: [kangarooking/cangjie-skill](https://github.com/kangarooking/cangjie-skill)
- Tags: how-to-guide
- Published: 2026-07-19

---

**To resume a broken cangjie-skill pipeline, edit the [`PIPELINESTATE.md`](https://github.com/kangarooking/cangjie-skill/blob/main/PIPELINESTATE.md) file in the repository root to reset the failed stage from ❌ to ⏳ (pending), then re-run `python -m cangjie.pipeline` to restart from that stage while automatically skipping previously completed work.**

The `kangarooking/cangjie-skill` repository implements a seven-stage RIA-TV++ pipeline that transforms raw text into structured AI skills. When execution halts due to crashes, timeouts, or manual interruptions, the pipeline state persists in [`PIPELINESTATE.md`](https://github.com/kangarooking/cangjie-skill/blob/main/PIPELINESTATE.md), allowing you to resume cangjie-skill pipeline operations without reprocessing the Adler, Parallel Extract, or other successfully finished stages.

## Understanding the Pipeline State File

[`PIPELINESTATE.md`](https://github.com/kangarooking/cangjie-skill/blob/main/PIPELINESTATE.md) lives in the repository root (`<repo-root>/PIPELINESTATE.md`) and serves as the single source of truth for execution progress. This human-readable Markdown file contains a table tracking the seven methodology stages: **Adler**, **Parallel Extract**, **Triple Verification**, **RIA++ Construction**, **Zettelkasten Linking**, **Pressure Test**, and **Delivery**. Each row displays a status emoji: ✅ for completed, ❌ for error, ⏸ for paused, and ⏳ for pending.

## Step-by-Step Recovery Process

### Locate the State File

Navigate to the repository root and open [`PIPELINESTATE.md`](https://github.com/kangarooking/cangjie-skill/blob/main/PIPELINESTATE.md) in any text editor. The file structure mirrors the seven-stage workflow defined in [`methodology/00-overview.md`](https://github.com/kangarooking/cangjie-skill/blob/main/methodology/00-overview.md) and the master specification in [`SKILL.md`](https://github.com/kangarooking/cangjie-skill/blob/main/SKILL.md).

### Identify the Failed Stage

Scan the Status column for the last ✅ symbol. The stage immediately below it bearing ❌ or ⏸ indicates where execution stopped. For example, if **2 – Parallel Extract** shows ❌, the pipeline failed while running the five parallel extractors (framework, principle, case, counter-example, and glossary) defined in `extractors/*.md`.

### Reset Stages to Pending

Change the status of the failed stage—and any subsequent stages—from ❌ or ⏸ to **⏳** (pending). Save the file. This modification signals the runner to re-execute these specific stages while preserving work already validated in earlier steps.

```markdown

# PIPELINESTATE.md

| Stage | Status |
|-------|--------|
| 1 – Adler                     | ✅ |
| 2 – Parallel Extract          | ⏳ |   <!-- changed from ❌ -->
| 3 – Triple Verification       | ⏸ |
| 4 – RIA++ Construction        | ⏸ |
| 5 – Zettelkasten Linking      | ⏸ |
| 6 – Pressure Test             | ⏸ |
| 7 – Delivery                  | ⏸ |

```

### Clean Up Partial Outputs (Optional)

If the failed stage produced incomplete artifacts—such as fragmented [`SKILL.md`](https://github.com/kangarooking/cangjie-skill/blob/main/SKILL.md) files or corrupted entries in the `output/` directory—delete or archive them before restarting. This prevents the extractor from detecting existing files and assuming the stage succeeded, which would mix corrupted data with fresh results.

### Restart the Pipeline

Execute the pipeline command from the repository root:

```bash
python -m cangjie.pipeline

```

Alternatively, use the Make wrapper if configured in your environment:

```bash
make pipeline

```

The runner script reads [`PIPELINESTATE.md`](https://github.com/kangarooking/cangjie-skill/blob/main/PIPELINESTATE.md), detects the ⏳ status on the interrupted stage, and resumes execution from that point, skipping stages marked ✅.

## Advanced Recovery Options

### Force Start from a Specific Stage

To bypass automatic state detection and explicitly begin at a specific stage, use the `--start-stage` flag:

```bash
python -m cangjie.pipeline --start-stage 2

```

This command internally reads [`PIPELINESTATE.md`](https://github.com/kangarooking/cangjie-skill/blob/main/PIPELINESTATE.md) but overrides the pending check to force execution to begin at stage 2 (Parallel Extract), regardless of the current status emoji.

## Verification and Output

After the run completes, verify that [`PIPELINESTATE.md`](https://github.com/kangarooking/cangjie-skill/blob/main/PIPELINESTATE.md) displays ✅ for all seven stages. Confirm successful regeneration by checking the `output/` directory for [`BOOK_OVERVIEW.md`](https://github.com/kangarooking/cangjie-skill/blob/main/BOOK_OVERVIEW.md), [`INDEX.md`](https://github.com/kangarooking/cangjie-skill/blob/main/INDEX.md), and [`DIGEST.md`](https://github.com/kangarooking/cangjie-skill/blob/main/DIGEST.md), along with the individual skill modules generated by the templates in `templates/`.

## Summary

- **Single source of truth**: [`PIPELINESTATE.md`](https://github.com/kangarooking/cangjie-skill/blob/main/PIPELINESTATE.md) controls resumption; modify only the Status column, as stage names and order are fixed by the RIA-TV++ methodology.
- **Safe to retry**: Stages marked ✅ are automatically skipped during restart, preventing redundant processing.
- **Manual reset required**: Change failed stages from ❌ to ⏳ to trigger re-execution.
- **Cleanup recommended**: Remove partial [`SKILL.md`](https://github.com/kangarooking/cangjie-skill/blob/main/SKILL.md) fragments or broken files from the `output/` directory to avoid data corruption.
- **Entry points**: Use `python -m cangjie.pipeline` or `make pipeline` to resume; add `--start-stage N` to force a specific starting point.

## Frequently Asked Questions

### What happens if I don't clean up partial outputs from a failed stage?

The extractor scripts may detect existing files and assume the stage completed successfully, causing the pipeline to skip necessary work. This risks mixing corrupted data with fresh results, so always remove incomplete artifacts from the `output/` folder or `*/SKILL.md` paths before resuming.

### Can I resume the pipeline if I accidentally deleted PIPELINESTATE.md?

If the state file is missing, the pipeline assumes a fresh start and will execute all seven stages from the beginning. Without [`PIPELINESTATE.md`](https://github.com/kangarooking/cangjie-skill/blob/main/PIPELINESTATE.md), the system cannot determine which steps completed successfully, so you must reprocess the entire workflow.

### Does the --start-stage flag permanently modify PIPELINESTATE.md?

No, the `--start-stage` flag only affects the current execution session. While the pipeline reads the state file internally to locate resources, you must manually edit [`PIPELINESTATE.md`](https://github.com/kangarooking/cangjie-skill/blob/main/PIPELINESTATE.md) to permanently change stage statuses for subsequent runs.

### Where can I find logs to debug why a stage keeps failing?

Inspect the error messages recorded in [`PIPELINESTATE.md`](https://github.com/kangarooking/cangjie-skill/blob/main/PIPELINESTATE.md) and check the `log/` directory or stdout output from the verification scripts. The methodology documentation in [`methodology/00-overview.md`](https://github.com/kangarooking/cangjie-skill/blob/main/methodology/00-overview.md) explains each stage's validation criteria, helping you identify why the Triple Verification or Pressure Test stages repeatedly error out.