I did a little vibe thingie.
As network engineers and security managers, we face a constant challenge: keeping our documentation current. Whether it’s network diagrams, incident response plans, security policies, or configuration guides, documentation has a tendency to become outdated the moment we finish writing it.
The consequences of stale documentation in critical infrastructure environments can be severe. An outdated firewall rule document might lead to misconfigurations. An old incident response plan might reference tools or procedures that no longer exist. A security policy that hasn’t been reviewed in two years might miss critical compliance requirements.
But here’s the thing: we all know documentation needs regular reviews. We set good intentions. We even add review dates to our files. And then… life happens. Projects pile up. Tickets flood in. And before we know it, that quarterly review we planned six months ago is now hopelessly overdue.
The Problem with Manual Tracking
If you’re using org-mode to manage your documentation (and if you’re reading this, chances are you do), you might already be tracking review dates in property drawers:
* Firewall Configuration Documentation
:PROPERTIES:
:Created: 2024-01-15
:Revisited: 2024-06-01
:NextReview: 2024-09-01
:ReviewCycle: 90
:Status: Current
:END:
This is great practice. The problem is: how do you actually track all these review dates across dozens or hundreds of documents? Do you manually check each file? Create calendar reminders for each document? Build complex org-agenda queries?
A Lightweight Solution
This is why I created org-review-checker - a simple Python tool that scans your org files and tells you exactly which documents need attention.
It does one thing well: it walks through your org file directories and checks the review status of every document. No complex setup, no database, no dependencies beyond Python’s standard library. Just point it at your documentation directory and get a clear report.
What It Checks
The tool looks for three key properties in your org headings or file headers:
- Created: When was this document first written?
- Revisited: When was it last reviewed?
- NextReview: When should it be reviewed again?
Based on these dates, it categorizes documents into:
- Overdue reviews - Documents past their review date
- Upcoming reviews - Documents due within the next 30 days
- Missing properties - Documents that aren’t being tracked yet
- Current - Documents that are up to date
Real-World Output
Here’s what a typical report looks like:
================================================================================
DOCUMENT REVIEW STATUS REPORT
================================================================================
Files scanned: 23
Documents with missing properties: 5
Overdue reviews: 3
Upcoming reviews (next 30 days): 4
⚠️ OVERDUE REVIEWS
--------------------------------------------------------------------------------
📄 network/firewall-rules.org
• DMZ Firewall Configuration
Due: 2024-09-01 (102 days overdue)
Last reviewed: 2024-06-01
📄 security/incident-response.org
• DDoS Response Plan
Due: 2024-11-01 (40 days overdue)
Last reviewed: 2024-08-01
❌ MISSING REVIEW PROPERTIES
--------------------------------------------------------------------------------
📄 policies/password-policy.org
• Password Requirements
Missing: Created, Revisited, NextReview
📅 UPCOMING REVIEWS (Next 30 days)
--------------------------------------------------------------------------------
📄 network/topology.org
• Network Diagram
Due: 2025-01-05 (in 25 days)
✅ 15 documents are current (reviews > 30 days away)
Suddenly, you have visibility. You know exactly what needs attention and when.
Practical Use Cases
Pre-Audit Compliance Checks
Running quarterly security audits? Before the auditors arrive, scan your policy documentation:
uv run check_reviews.py /policies > audit_prep_report.txt
You’ll immediately see which policies haven’t been reviewed recently and can address them before they become audit findings.
Weekly Team Reports
Add it to your cron jobs to get weekly reminders:
0 9 * * 1 cd /docs && uv run check_reviews.py . | mail -s "Doc Review Status" team@example.com
Every Monday morning, your team gets a clear picture of documentation health.
Integration with Existing Workflows
Since the tool works with standard org-mode property drawers, it integrates seamlessly with your existing org-agenda setup. You can continue using your current workflow while adding automated compliance tracking.
A Bonus: Git History Integration
One challenge when starting to track documentation reviews is filling in the historical data. When was each document actually created?
The included set_created_dates.py helper solves this by automatically setting the Created property based on your git history. It finds the first commit for each file and uses that date:
# Preview what will change
uv run set_created_dates.py --dry-run --directory ./docs
# Apply the changes
uv run set_created_dates.py --directory ./docs
This gives you historically accurate creation dates without manual entry.
Design Philosophy
The tool follows a few key principles:
Zero Dependencies: Uses only Python’s standard library. No pip install headaches, no version conflicts, no virtual environment issues to debug.
Read-Only by Default: It never modifies your files during checks. You stay in control of your documentation.
Flexible Structure: Works with both file-level properties (one review schedule per file) and heading-level properties (multiple reviewable sections per file). Use the --header-only flag if you prefer file-level tracking.
Plain Text: All data stays in your org files as plain text. No hidden databases, no proprietary formats. You can read and edit everything in Emacs.
Who Is This For?
This tool is specifically designed for:
- Network engineers managing infrastructure documentation
- Security teams maintaining compliance policies
- System administrators tracking configuration guides
- IT managers ensuring knowledge bases stay current
- Anyone using org-mode for technical documentation who needs review compliance
If you’re responsible for keeping critical documentation current and you use org-mode, this tool can help.
Getting Started
The tool is open source and available now. Installation is straightforward:
git clone https://forgejo.mayer.rocks/public/org-review-checker.git
cd org-review-checker
uv run check_reviews.py /path/to/your/docs
That’s it. No configuration files, no setup scripts, no database initialization.
Looking Forward
Current plans include adding CSV/JSON export for integration with external systems, email notifications for overdue reviews, and iCal export for calendar integration. But the core philosophy remains: keep it simple, keep it focused, keep it useful.
Documentation review compliance doesn’t have to be complicated. Sometimes you just need a tool that tells you what needs attention and gets out of your way.
Project: org-review-checker on Forgejo License: MIT Requirements: Python 3.8+, uv for dependency management