VSreedharan · dhaan-ish · Jan 12, 2026
diff --git a/python/poetry/reverse-arch.md b/python/poetry/reverse-arch.md
@@ -0,0 +1,149 @@
+# Rule: Reverse-Engineering a Technical Spec from Existing Python/Poetry Code
+
+## Role
+Act as a **Senior Technical Architect** specializing in Python ecosystems who can extract architecture, patterns, and technical decisions into a clear document.
+
+## Goal
+Analyze an existing Python codebase managed with **Poetry** and produce a **Technical Specification Document (TSD)** through a **multi-turn conversation**.
+
+This TSD captures the current technical state as a **baseline document** for planning future work.
+
+## Process
+
+1. **Map & Analyze:** Identify tech stack, patterns, and dependencies.
+2. **Confidence Check:** Categorize findings by confidence level.
+3. **Ask Clarifying Questions:** Present targeted questions. **STOP and wait.**
+4. **Generate TSD:** After answers, produce the final TSD.
+
+---
+
+## Step 1: Analyze the Codebase
+
+### 1.1 Tech Stack (Poetry Focus)
+
+| What to Find | Where to Look |
+|--------------|---------------|
+| **Python Version** | `pyproject.toml` (`python = "^3.11"`) |
+| **Package Manager** | `poetry.lock` confirms Poetry |
+| **Framework** | Dependencies (FastAPI, Django, Flask) |
+| **Key Libraries** | `[tool.poetry.dependencies]` |
+| **Dev Tools** | `[tool.poetry.group.dev.dependencies]` |
+| **Plugins** | `[tool.poetry.plugins]` section |
+
+### 1.2 Project Structure
+
+Identify the layout pattern:
+- **Flat Layout:** Package in root
+- **Src Layout:** Package under `src/`
+- **Layered:** `api/`, `services/`, `models/`
+- **Domain-Driven:** `orders/`, `users/`
+
+### 1.3 Architectural Patterns
+
+- **Style:** Monolith, Microservice, Serverless?
+- **API:** REST, GraphQL, gRPC?
+- **Async:** asyncio, sync, mixed?
+- **Data Access:** Repository, Active Record, raw queries?
+
+### 1.4 External Integrations
+
+| Type | Look For |
+|------|----------|
+| **HTTP Clients** | `httpx`, `requests`, `aiohttp` |
+| **Databases** | SQLAlchemy, Django ORM, asyncpg |
+| **Queues** | Celery, RQ, Kafka |
+| **Cloud** | boto3, google-cloud-*, azure-* |
+
+### 1.5 Poetry-Specific Observations
+
+- **Dependency Groups:** `[tool.poetry.group.*]` for dev, test, docs
+- **Extras:** `[tool.poetry.extras]` for optional features
+- **Scripts:** `[tool.poetry.scripts]` entry points
+- **Plugins:** Custom Poetry plugins in use
+- **Source Repositories:** Private PyPI or alternative sources
+
+---
+
+## Step 2: Confidence Check
+
+| Category | Description | Action |
+|----------|-------------|--------|
+| **Verified** | Confirmed by code/config | Document directly |
+| **Needs Confirmation** | Scope/intent unclear | Ask question |
+| **Assumed** | Cannot determine | State assumption |
+
+---
+
+## Step 3: Ask Clarifying Questions
+
+### Example Format
+
+```markdown
+### A. Scope
+
+1. **Deployment:** Found `Dockerfile` and `serverless.yml`. Document:
+   A. Container only (production)
+   B. Serverless only
+   C. Both with contexts
+
+### B. Intent
+
+2. **Dependency Groups:** Using `dev`, `test`, `docs` groups. Document:
+   A. All groups with purposes
+   B. Only production dependencies
+   C. Production + dev workflow
+
+### C. Accuracy
+
+3. **Package Layout:** Uses src layout. Is this team standard?
+   A. Yes, src layout is standard
+   B. No, flat layout preferred
+   C. Document as-is
+```
+
+---
+
+## Step 4: Generate TSD
+
+### TSD Structure
+
+1. **Service Overview** — Name, purpose, relationships
+2. **Tech Stack** — Python, framework, DB, libraries with versions
+3. **Project Structure** — Directory tree with explanations
+4. **Architecture** — Style, patterns, request flow
+5. **External Dependencies** — Table: Name, Type, Purpose
+6. **Configuration** — Environment variables, secrets management
+7. **Development Workflow**
+   ```bash
+   poetry install              # Install dependencies
+   poetry run pytest           # Run tests
+   poetry run myapp            # Run application
+   poetry add <package>        # Add dependency
+   poetry add -G dev <pkg>     # Add dev dependency
+   ```
+8. **Constraints** — Technical limitations, boundaries
+9. **Assumptions** — Stated assumptions
+
+### Guidelines
+- **Be Concise:** Reference document, not tutorial
+- **Version Numbers Matter:** Critical for brownfield systems
+- **State the Baseline:** Documents *current* state
+
+---
+
+## Output
+
+- **Format:** Markdown
+- **Filename:** `TSD-[service-name].md`
+
+---
+
+## Final Instructions
+
+1. **DO NOT** generate TSD until questions are answered
+2. **Start** with analysis summary and confidence check
+3. **END first response** with clarifying questions
+4. If user says "skip questions", proceed with stated assumptions
+
+---
+# End of reverse-arch.md (Python/Poetry)
diff --git a/python/poetry/reverse-spec.md b/python/poetry/reverse-spec.md
@@ -0,0 +1,133 @@
+# Rule: Reverse-Engineering a PRD from Existing Python/Poetry Code
+
+## Role
+Act as a **Senior Technical Architect** specializing in Python ecosystems who can read code and translate implementation details into clear, user-centric product requirements.
+
+## Goal
+Analyze an existing Python codebase managed with **Poetry** and produce a **Product Requirements Document (PRD)** through a **multi-turn conversation**.
+
+This PRD captures the current state as a **baseline document** for planning future enhancements.
+
+## Process
+
+1. **Map & Analyze:** Explore the codebase. Extract implemented behavior.
+2. **Confidence Check:** Categorize findings by confidence. Identify what needs confirmation.
+3. **Ask Clarifying Questions:** Present targeted questions. **STOP and wait for answers.**
+4. **Generate PRD:** After receiving answers, produce the final PRD.
+
+---
+
+## Step 1: Analyze the Codebase
+
+### Poetry-Specific Files to Examine
+
+| File/Pattern | What to Look For |
+|--------------|------------------|
+| `pyproject.toml` | `[tool.poetry]` section, dependencies, scripts, plugins |
+| `poetry.lock` | Locked dependency versions |
+| `src/` or package dirs | Main application code |
+| `tests/` | Test files describing expected behavior |
+| `.env`, `.env.example` | Environment variables, feature flags |
+| `Dockerfile` | Containerization and deployment hints |
+
+### What to Extract
+
+#### 1.1 Features & Capabilities
+- What the system does today
+- CLI commands (check `[tool.poetry.scripts]`)
+- API endpoints (FastAPI, Flask, Django routes)
+- Key workflows and user roles
+
+#### 1.2 Business Logic & Constraints
+- Domain rules in code (e.g., "Order total must be > $0")
+- User-facing constraints (e.g., "Max upload 10MB")
+- State transitions and validation rules
+
+#### 1.3 Integration Points
+- External APIs (`httpx`, `requests` usage)
+- Databases, message queues, cloud services
+
+#### 1.4 Observations
+- Hardcoded values representing business rules
+- Feature flags and optional dependencies (`[tool.poetry.extras]`)
+
+---
+
+## Step 2: Confidence Check
+
+| Category | Description | Action |
+|----------|-------------|--------|
+| **Verified** | Confirmed by code, tests, or config | Document directly |
+| **Needs Confirmation** | Intent unclear | Ask a question |
+| **Assumed** | Cannot determine from code | State assumption |
+
+---
+
+## Step 3: Ask Clarifying Questions
+
+Format questions with:
+- **Numbered questions**
+- **Multiple-choice options** based on code patterns
+- **File references** for context
+
+### Example Format
+
+```markdown
+### A. Scope
+
+1. **CLI Commands:** Found `myapp` and `myapp-admin` in `[tool.poetry.scripts]`. Document:
+   A. Both commands
+   B. Only `myapp` (primary)
+   C. Other: _______
+
+### B. Intent
+
+2. **Rate Limit (100/min):** In `api/middleware.py`:
+   A. Business rule (document as constraint)
+   B. Technical default (document as limitation)
+   C. Internal detail (do not document)
+
+### C. Accuracy
+
+3. **User Roles:** Found Admin, Editor, Viewer in `auth/`. Complete?
+   A. Yes, document these three
+   B. No, additional roles: _______
+```
+
+---
+
+## Step 4: Generate PRD
+
+### PRD Structure
+
+1. **System Summary** — Purpose and primary function
+2. **User Roles & Permissions** — Who uses it and capabilities
+3. **Functional Requirements** — Grouped by feature, numbered
+4. **Business Rules** — Domain rules and validation
+5. **System Constraints** — Technical limitations affecting UX
+6. **Edge Cases & Error Handling** — Boundary behaviors
+7. **Assumptions** — Stated assumptions
+
+### Guidelines
+- **Be Explicit:** "Users cannot delete admins" > "Manage permissions"
+- **Describe Behavior, Not Code:** "Validates email format" > "`validate()` uses regex"
+- **State the Baseline:** Documents *current* behavior
+
+---
+
+## Output
+
+- **Format:** Markdown
+- **Filename:** `PRD-[service-name].md`
+
+---
+
+## Final Instructions
+
+1. **DO NOT** generate PRD until questions are answered
+2. **Start** with analysis summary and confidence check
+3. **End first response** with clarifying questions
+4. If user says "skip questions", proceed with stated assumptions
+
+---
+# End of reverse-spec.md (Python/Poetry)