phi-redactor 0.1.0__tar.gz

phi_redactor-0.1.0/.claude/commands/sp.adr.md

@@ -0,0 +1,207 @@
+---
+description: Review planning artifacts for architecturally significant decisions and create ADRs.
+---
+
+# COMMAND: Analyze planning artifacts and document architecturally significant decisions as ADRs
+
+## CONTEXT
+
+The user has completed feature planning and needs to:
+
+- Identify architecturally significant technical decisions from plan.md
+- Document these decisions as Architecture Decision Records (ADRs)
+- Ensure team alignment on technical approach before implementation
+- Create a permanent, reviewable record of why decisions were made
+
+Architecture Decision Records capture decisions that:
+
+- Impact how engineers write or structure software
+- Have notable tradeoffs or alternatives
+- Will likely be questioned or revisited later
+
+**User's additional input:**
+
+$ARGUMENTS
+
+## YOUR ROLE
+
+Act as a senior software architect with expertise in:
+
+- Technical decision analysis and evaluation
+- System design patterns and tradeoffs
+- Enterprise architecture documentation
+- Risk assessment and consequence analysis
+
+## OUTPUT STRUCTURE (with quick flywheel hooks)
+
+Execute this workflow in 6 sequential steps. At Steps 2 and 4, apply lightweight Analyze→Measure checks:
+ - Analyze: Identify likely failure modes, specifically:
+     - Over-granular ADRs: ADRs that document decisions which are trivial, low-impact, or do not affect architectural direction (e.g., naming conventions, minor refactorings).
+     - Missing alternatives: ADRs that do not list at least one alternative approach considered.
+ - Measure: Apply the following checklist grader (PASS only if all are met):
+     - The ADR documents a decision that clusters related changes or impacts multiple components (not a trivial/single-file change).
+     - The ADR explicitly lists at least one alternative approach, with rationale.
+     - The ADR includes clear pros and cons for the chosen approach and alternatives.
+     - The ADR is concise but sufficiently detailed for future reference.
+
+## Step 1: Load Planning Context
+
+Run `.specify/scripts/powershell/check-prerequisites.ps1 -Json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS.
+
+Derive absolute paths:
+
+- PLAN = FEATURE_DIR/plan.md (REQUIRED - abort if missing with "Run /sp.plan first")
+- RESEARCH = FEATURE_DIR/research.md (if exists)
+- DATA_MODEL = FEATURE_DIR/data-model.md (if exists)
+- CONTRACTS_DIR = FEATURE_DIR/contracts/ (if exists)
+
+## Step 2: Extract Architectural Decisions (Analyze)
+
+Load plan.md and available artifacts. Extract architecturally significant decisions as **decision clusters** (not atomic choices):
+
+**✅ GOOD (Clustered):**
+
+- "Frontend Stack" (Next.js + Tailwind + Vercel as integrated solution)
+- "Authentication Approach" (JWT strategy + Auth0 + session handling)
+- "Data Architecture" (PostgreSQL + Redis caching + migration strategy)
+
+**❌ BAD (Over-granular):**
+
+- Separate ADRs for Next.js, Tailwind, and Vercel
+- Separate ADRs for each library choice
+
+**Clustering Rules:**
+
+- Group technologies that work together and would likely change together
+- Separate only if decisions are independent and could diverge
+- Example: Frontend stack vs Backend stack = 2 ADRs (can evolve independently)
+- Example: Next.js + Tailwind + Vercel = 1 ADR (integrated, change together)
+
+For each decision cluster, note: what was decided, why, where in docs.
+
+## Step 3: Check Existing ADRs
+
+Scan `history/adr/` directory. For each extracted decision:
+
+- If covered by existing ADR → note reference
+- If conflicts with existing ADR → flag conflict
+- If not covered → mark as ADR candidate
+
+## Step 4: Apply Significance Test (Measure)
+
+For each ADR candidate, test:
+
+- Does it impact how engineers write/structure software?
+- Are there notable tradeoffs or alternatives?
+- Will it be questioned or revisited later?
+
+Only proceed with ADRs that pass ALL three tests.
+
+## Step 5: Create ADRs (Improve)
+
+For each qualifying decision cluster:
+
+1. Generate concise title reflecting the cluster (e.g., "Frontend Technology Stack" not "Use Next.js")
+2. Run `create-adr.sh "<title>"` from repo root
+3. Parse JSON response for `adr_path` and `adr_id`
+4. Read created file (contains template with {{PLACEHOLDERS}})
+5. Fill ALL placeholders:
+   - `{{TITLE}}` = decision cluster title
+   - `{{STATUS}}` = "Proposed" or "Accepted"
+   - `{{DATE}}` = today (YYYY-MM-DD)
+   - `{{CONTEXT}}` = situation, constraints leading to decision cluster
+   - `{{DECISION}}` = list ALL components of cluster (e.g., "Framework: Next.js 14, Styling: Tailwind CSS v3, Deployment: Vercel")
+   - `{{CONSEQUENCES}}` = outcomes, tradeoffs, risks for the integrated solution
+   - `{{ALTERNATIVES}}` = alternative clusters (e.g., "Remix + styled-components + Cloudflare")
+   - `{{REFERENCES}}` = plan.md, research.md, data-model.md
+6. Save file
+
+## Step 6: Report Completion
+
+Output:
+
+```
+✅ ADR Review Complete - Created N ADRs, referenced M existing
+```
+
+List created ADRs with ID and title.
+
+If conflicts detected:
+
+```
+⚠️ Conflicts with existing ADRs [IDs]. Review and update outdated decisions or revise plan.
+```
+
+If create-adr.sh fails: Report script error and skip that ADR.
+
+## FORMATTING REQUIREMENTS
+
+Present results in this exact structure:
+
+```
+✅ ADR Review Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Created ADRs: {count}
+   - ADR-{id}: {title}
+   - ADR-{id}: {title}
+
+📚 Referenced Existing: {count}
+   - ADR-{id}: {title}
+
+⚠️  Conflicts Detected: {count}
+   - ADR-{id}: {conflict description}
+
+Next Steps:
+→ Resolve conflicts before proceeding to /sp.tasks
+→ Review created ADRs with team
+→ Update plan.md if needed
+
+Acceptance Criteria (PASS only if all true)
+- Decisions are clustered (not atomic), with explicit alternatives and tradeoffs
+- Consequences cover both positive and negative outcomes
+- References link back to plan and related docs
+```
+
+## ERROR HANDLING
+
+If plan.md missing:
+
+- Display: "❌ Error: plan.md not found. Run /sp.plan first to generate planning artifacts."
+- Exit gracefully without creating any ADRs
+
+If create-adr.sh fails:
+
+- Display exact error message
+- Skip that ADR and continue with others
+- Report partial completion at end
+
+## TONE
+
+Be thorough, analytical, and decision-focused. Emphasize the "why" behind each decision and its long-term implications.
+
+---
+
+As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
+
+1) Determine Stage
+   - Stage: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate Title and Determine Routing:
+   - Generate Title: 3–7 words (slug for filename)
+   - Route is automatically determined by stage:
+     - `constitution` → `history/prompts/constitution/`
+     - Feature stages → `history/prompts/<feature-name>/` (spec, plan, tasks, red, green, refactor, explainer, misc)
+     - `general` → `history/prompts/general/`
+
+3) Create and Fill PHR (Shell first; fallback agent‑native)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
+   - If the script fails:
+     - Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
+     - Allocate an ID; compute the output path based on stage from step 2; write the file
+     - Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
+
+4) Validate + report
+   - No unresolved placeholders; path under `history/prompts/` and matches stage; stage/title/date coherent; print ID + path + stage + title.
+   - On failure: warn, don't block. Skip only for `/sp.phr`.

phi_redactor-0.1.0/.claude/commands/sp.analyze.md

@@ -0,0 +1,210 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/sp.tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/sp.analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Non-Functional Requirements
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.specify/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Non-functional requirements not reflected in tasks (e.g., performance, security)
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/sp.implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /sp.specify with refinement", "Run /sp.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+$ARGUMENTS
+
+---
+
+As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
+
+1) Determine Stage
+   - Stage: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate Title and Determine Routing:
+   - Generate Title: 3–7 words (slug for filename)
+   - Route is automatically determined by stage:
+     - `constitution` → `history/prompts/constitution/`
+     - Feature stages → `history/prompts/<feature-name>/` (spec, plan, tasks, red, green, refactor, explainer, misc)
+     - `general` → `history/prompts/general/`
+
+3) Create and Fill PHR (Shell first; fallback agent‑native)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
+   - If the script fails:
+     - Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
+     - Allocate an ID; compute the output path based on stage from step 2; write the file
+     - Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
+
+4) Validate + report
+   - No unresolved placeholders; path under `history/prompts/` and matches stage; stage/title/date coherent; print ID + path + stage + title.
+   - On failure: warn, don't block. Skip only for `/sp.phr`.