- Home
- Skills
- Technical Documentation
- Decision Journal
Works with the AI Agents you already use
Decision Journal
Capture architectural trade-offs and technical decisions in a searchable, numbered Markdown journal.
$5.99
Decision Journal
Example session with this skill installed
We decided to use Redis for the caching layer instead of Memcached because we need the data persistence and built-in pub/sub features. Record this as a new decision.
- Read your context and instructions
- Compiled the decision journal
I have recorded the decision to use Redis for the caching layer. A new entry has been created and the index has been updated.
Decision Recorded: 0005-redis-caching-layer.md
| Field | Value |
|---|---|
| ID | 0005 |
| Status | accepted |
| Title | Use Redis for caching layer |
| Decision | Chose Redis over Memcached because we require RDB/AOF persistence and pub/sub capabilities for future real-time updates. |
| Tags | infrastructure, caching, redis |
| File Path | docs/decisions/0005-redis-caching-layer.md |
Entry Preview
Context
The application requires a shared cache across multiple instances. While basic key-value storage is the primary need, our roadmap includes real-time notifications and we cannot risk a full cache wipe on service restarts.
Consequences
- Benefit: Reduced latency for pub/sub operations compared to a separate MQ.
- Benefit: Durable cache state across deployments.
- Cost: Increased operational complexity compared to Memcached's simpler memory model.
- Revisit: If memory overhead becomes a bottleneck or persistence is moved to the primary DB.
Next steps
- Review
docs/decisions/0005-redis-caching-layer.mdto ensure the consequences list is exhaustive. - Commit the new file and the updated
docs/decisions/INDEX.md. - Reference this decision ID in the cache initialization module comments.
Connects securely to your tools. The creator never sees your data.
About this skill
Technical projects often suffer from "lost context" where later developers can see what was built but not why specific trade-offs were made. This skill implements a disciplined Decision Journal (ADR) system within your repository to capture architectural reasoning at the moment of choice. It prevents re-litigating old debates and ensures every technical constraint is documented alongside its rejected alternatives.
What it does
- Formalizes trade-offs by enforcing a "Chose X over Y because Z" format for all technical decisions.
- Automates ADR creation using a provided script to generate numbered, timestamped Markdown entries.
- Manages decision lifecycles by handling supersession and deprecation to prevent circular reasoning.
- Indexes architecture in a central
INDEX.mdfor fast grep-based or script-based retrieval. - Validates reasoning by ensuring every entry includes context, consequences, and a named alternative.
How it works
- Search the existing journal using
decision.sh searchto see if a standing decision already covers the current problem. - Initialize a new entry with
decision.sh new "<title>"when a choice constrains future work or overrides a default. - Document the specific context, the rejected option, and the long-term consequences in the generated Markdown file.
- Supersede old entries when architectural directions change, creating a clear audit trail of the project's evolution.
Frameworks & tools
This skill uses Bash scripts for automation and standard Markdown for storage. It is compatible with any repository structure but defaults to docs/decisions/.
Why this beats prompting it yourself
Generic LLMs often provide "notes" rather than "decisions," missing the critical rejected alternatives that make an ADR useful. This skill enforces a strict schema that ensures reasoning is actually testable and reversible by future developers.
Use cases
- Documenting why a specific database or storage engine was chosen over common alternatives.
- Recording the reasoning for specific API contract shapes or authentication models.
- Tracking the evolution of project standards, such as choosing a specific testing library.
- Capturing "hidden" preferences from senior developers that aren't obvious in the code.
Known limitations
Does not support multi-decision entries; each choice requires a unique file to maintain clean supersession chains. Logic is restricted to local filesystem operations.
Requires one decision per entry. Only manages local Markdown files. Does not integrate with external project management tools like Jira or Linear.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 1 month ago