irp-capture 0.1.0__tar.gz

irp_capture-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johan Lopes Helgesson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

irp_capture-0.1.0/PKG-INFO

@@ -0,0 +1,365 @@
+Metadata-Version: 2.4
+Name: irp-capture
+Version: 0.1.0
+Summary: An append-only ledger that records why decisions were made.
+License: MIT
+Keywords: decision-log,local-first,append-only,devtools,ai,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# irp-capture
+
+## Intent Record Protocol
+
+**IRP is a decision ledger that records why things were done.**
+
+Confirm a decision → it is written to a local file → it stays forever.
+
+```bash
+# Before starting something new
+irp why
+
+# IRP-2026-04-08-001  Decision: Use Postgres for the reporting service
+# Why: Redis rejected — query patterns require joins
+#
+# → No need to reopen this debate
+```
+
+---
+
+Three sprints ago your team made a hard call on the architecture.
+Everyone was in the room. It was the right decision, for the right reasons.
+Last week, someone reopened the debate.
+Because the reasoning was not written down anywhere.
+
+This is not a memory problem. It is a meaning problem.
+
+---
+
+## Who this is for
+
+IRP is designed for teams making decisions together:
+
+- Engineering teams choosing between approaches
+- Design and product teams approving creative direction
+- Pre-sales and delivery teams aligning on scope
+
+If you are working alone, this may feel unnecessary.
+If you are working in a team, it becomes obvious quickly.
+
+---
+
+## The reasoning gap
+
+AI tools are everywhere in your workflow now.
+Prompts, reviews, approvals, feedback loops.
+Good reasoning happens constantly. Almost none of it is preserved.
+
+Not because it was not captured somewhere.
+But because nothing was designed to capture *why*.
+
+Six months later:
+
+- A new engineer asks why the architecture was designed this way.
+- An audit asks which human approved this creative direction.
+- A product decision gets relitigated because no one remembers the reasoning.
+
+Every new AI session starts from zero.
+Every new team member re-learns what was already decided.
+Every tool has logs of *what happened*. None of them record *why it mattered*.
+
+> Storing everything is easy. Knowing what mattered is not.
+
+---
+
+## Before / After
+
+**Without IRP**
+
+```
+New engineer joins
+→ asks why the system works this way
+→ team debates again
+→ decision gets re-made
+```
+
+**With IRP**
+
+```
+New engineer joins
+→ runs `irp why`
+→ sees the decision and the reasoning
+→ moves forward without reopening it
+```
+
+---
+
+## What IRP does
+
+IRP is an append-only decision ledger that lives alongside your work.
+
+Think of it as a ship's log.
+Every course correction. Every judgment call. Every hard decision.
+Not because the ocean would remember — but because the next watch
+needs to know why the ship is where it is.
+
+When a human confirms a decision, IRP records it.
+That is the entire model.
+
+No AI inference. No automatic capture. No vector search.
+A human confirms a decision. IRP records it.
+The ledger is a plain text file. It never changes an existing entry.
+
+```
+.irp/
+  ledger.jsonl     ← append-only canonical record
+  current.json     ← last 10 decisions, derived from ledger
+```
+
+Every entry looks like this:
+
+```json
+{
+  "id": "IRP-2026-04-08-001",
+  "timestamp": "2026-04-08T14:32:11Z",
+  "decision": "Use Postgres for the reporting service",
+  "why": "Redis was considered but rejected. The query patterns require joins that do not map cleanly to key-value. Team aligned on this in the April 8 architecture review.",
+  "source": "cli",
+  "confirmed_by": "johan",
+  "context": "Backend infrastructure Q2 2026"
+}
+```
+
+Open the file. Read it. No tooling required.
+
+---
+
+## The human confirmation invariant
+
+IRP does not decide what matters. You do.
+
+Every entry in the ledger was confirmed by a human.
+This is not a design limitation. It is the point.
+
+An AI can produce a hundred options.
+Only one was chosen, and someone chose it for a reason.
+That reason is what IRP captures.
+
+This makes the ledger auditable, defensible, and trustworthy
+in a way that ambient memory systems cannot be.
+
+---
+
+## Under the hood
+
+| Component | Choice | Why |
+|---|---|---|
+| Storage | Append-only `.jsonl` flat file | Human-readable, no database required |
+| Retrieval | Deterministic — read the ledger | No embeddings, no similarity guessing |
+| Capture | Human-confirmed via sensor | No AI decides what matters |
+| Format | Plain JSON per line | Works in any editor, any language |
+| Dependencies | Python 3.9+, no cloud | Runs entirely on your machine |
+
+No ChromaDB. No vector index. No model dependency.
+The ledger is the truth. Not an approximation of it.
+
+---
+
+## Get started
+
+```bash
+pip install irp-capture
+```
+
+```bash
+# Set the context for your project
+irp inherit "Project: My project — backend API, Q2 2026"
+
+# Capture a decision
+irp capture "Decision: Use Postgres for the reporting service" \
+  --why "Redis considered but rejected — query patterns require joins"
+
+# Review recent decisions
+irp why
+```
+
+```
+# Output:
+# IRP-2026-04-08-001
+# Decision: Use Postgres for the reporting service
+# Why: Redis considered but rejected — query patterns require joins
+#
+# → No need to reopen this debate
+```
+
+The ledger is created at `.irp/ledger.jsonl` in your working directory.
+That file is yours. It does not leave your machine unless you choose.
+
+---
+
+## Sensors
+
+Sensors are optional. The ledger is the system.
+
+IRP captures decisions from the tools your team already uses.
+Nothing changes about how you work.
+
+| Sensor | How it captures |
+|---|---|
+| **Claude Code skill** | Type `capture` inside any Claude session. Captures the decision the moment it is made, without leaving your workflow. |
+| **CLI** | `irp capture` — capture any decision directly from the terminal |
+| **Slack** | Resolve a thread with a decision. The bot writes it to the ledger. |
+| **Figma** | Resolve a design comment. The plugin captures the decision. |
+| **Git hook** | Capture architecture decisions at commit time |
+| **More coming** | VS Code, PR bot, SDK for custom integrations |
+
+No tool talks to another. Everything talks to the ledger.
+
+---
+
+## Daily workflow
+
+**The highest-signal moment**
+
+When you are working with an AI assistant and a decision crystallises,
+that is when the reasoning is sharpest.
+The Claude Code skill lets you capture it without switching context.
+Type `capture`. The ledger is updated. You continue working.
+
+> The Claude skill captures decisions made *with* AI.
+> The ledger records decisions made *by* humans.
+
+**When to capture**
+
+Capture when a decision is made, not when you remember to.
+The sensors are designed to trigger at the natural confirmation moment —
+a Slack thread resolved, a Figma comment approved, a commit pushed.
+
+For decisions made in conversation or in a document, use the CLI:
+
+```bash
+irp capture "Decision: [what was decided]" --why "[why it was decided]"
+```
+
+**What makes a good entry**
+
+A good decision entry answers two questions:
+
+1. What did we choose?
+2. What did we reject, and why?
+
+The second question is the valuable one.
+Anyone can find what you chose. The rejected alternatives are what gets lost.
+
+**Review before starting something new**
+
+Before beginning a new phase, sprint, or project:
+
+```bash
+irp why
+```
+
+This shows the last 10 confirmed decisions.
+Takes 30 seconds. Prevents relitigating what was already decided.
+
+---
+
+## Common mistakes
+
+**Capturing too much**
+IRP is not a log. Do not capture every small choice.
+Capture decisions that would be hard to explain six months later.
+That is the right threshold.
+
+**Skipping the why**
+The decision text without the reasoning is just a log entry.
+The reasoning is what makes it worth keeping.
+If you cannot write one sentence of why, the decision may not be ready to capture yet.
+
+**Expecting search**
+The ledger is intentionally small.
+It is meant to be read, not queried.
+`irp why` shows your last 10 confirmed decisions in order.
+Read it the way you would read a ship's log.
+
+**Waiting until the end of a project**
+The value of IRP compounds over time.
+A decision captured the day it was made is worth ten decisions captured a month later.
+Start capturing from day one, even if the entries are simple.
+
+---
+
+## Quick reference
+
+| Task | Command |
+|---|---|
+| Capture inside a Claude session | `capture` (Claude Code skill) |
+| Set project context | `irp inherit "Project: [name and context]"` |
+| Capture a decision | `irp capture "Decision: [what]" --why "[why]"` |
+| Review recent decisions | `irp why` |
+| Review specific decision | `irp why --id IRP-2026-04-08-001` |
+| Capture from stdin | `irp capture --stdin` |
+| JSON output | Add `--json` to any command |
+
+---
+
+## Why not a memory tool?
+
+Memory stores what happened.
+
+Decisions explain why it mattered.
+
+IRP focuses on the second.
+
+---
+
+## Design principles
+
+- **Local-first.** The ledger lives on your machine. No cloud required.
+- **Append-only.** Entries are never edited or deleted. The record is immutable.
+- **Human-confirmed.** No entry exists without a human confirming it.
+- **Model-agnostic.** Works with Claude, GPT, Gemini, or no AI at all.
+- **Tool-agnostic.** Any sensor can write to the same substrate.
+- **Plain text.** The ledger is a `.jsonl` file. Open it in any editor.
+
+---
+
+## Status
+
+| Component | Status |
+|---|---|
+| Core CLI | Available |
+| Claude Code skill | Available |
+| Slack sensor | Available |
+| Figma plugin | In progress |
+| Git hook | In progress |
+| pip package | In progress |
+| SDK / API | Planned |
+
+---
+
+## Contributing
+
+IRP is used to capture real decisions across CLI and Slack workflows.
+It is early. If you are building in this space and the substrate
+model resonates, open an issue or reach out.
+
+The sensor pattern is open. If you want to write a sensor
+for a tool your team uses, the format is simple and documented.
+
+---
+
+*IRP does not tell you what to decide.
+It makes sure you remember why you did.*