CRISP Report Generator

Converts all markdown files in docs/ into a single self-contained HTML file — cards overview, click-through to full documents, beautiful dark theme, no dependencies.

---

How to run

Step 1: Check dependencies

pip3 install markdown pygments

If pip3 isn't available, try: python3 -m pip install markdown pygments

Step 2: Run the script

python3 scripts/generate-report.py [docs_dir] [output_file]

Defaults:

• docs_dir → ./docs
• output_file → ./crisp-report.html

Examples:

# Default — reads ./docs, outputs ./crisp-report.html
python3 scripts/generate-report.py

# Custom paths
python3 scripts/generate-report.py ./docs ./reports/sprint-3-report.html

Step 3: Open

open crisp-report.html

Or share the file directly — it's fully self-contained. No server needed.

---

What it produces

• Overview page — card grid, one card per document, grouped by section (Discovery / Spec / Archaeology / Execute)
• Document pages — click any card → full rendered document with proper typography, code highlighting, tables
• Escape / Back → returns to overview
• Direct URL linking via #doc-id hash — shareable links to specific docs

---

When to run

• End of CRISP Phase S — before handing off to Execute. Share with stakeholders for review.
• End of each sprint — updated report alongside the sprint delta doc. The stakeholder report section is already in the HTML.
• After CRISP Archaeology — share the recovered docs with the client or team.
• Any time — "generate report" at any point in a CRISP session.

---

Script location

scripts/generate-report.py in the project root (copied from the CRISP repo).

If the script doesn't exist in the project yet, instruct the user to copy it from the CRISP repo:

curl -o scripts/generate-report.py https://raw.githubusercontent.com/radekamirko/C.R.I.S.P/main/scripts/generate-report.py

Or copy it manually from C.R.I.S.P/scripts/generate-report.py.

---

Output file naming convention

When	Suggested name
Phase S complete	crisp-report.html
Sprint N close	crisp-report-sprint-N.html
Archaeology complete	crisp-report-archaeology.html
Ad hoc	crisp-report.html (overwrites)

---

Troubleshooting

ModuleNotFoundError: No module named 'markdown' → Run: pip3 install markdown pygments --break-system-packages

No markdown files found in docs/ → Make sure you're running from the project root, or pass the correct path: python3 scripts/generate-report.py ./path/to/docs

Docs are blank or broken → Check that docs are valid UTF-8 markdown. The script skips files it can't read.