feat: implement reusable feedback capability for continuous improvement

Add comprehensive feedback system that enables lightweight, unstructured feedback collection from users of the issue-facade capability, establishing a continuous improvement loop grounded in real-world usage. Core Components: - .feedback/ directory structure (inbound, reviewed, archived) - Standalone CLI tool (.capability/feedback) for submission and management - Comprehensive documentation (.feedback/README.md) - Integration examples and usage guides Key Features: - Multiple submission methods (CLI, Makefile, direct file drop) - No structure imposement - accepts any text/markdown format - Automatic metadata capture (timestamp, git context, version) - Maintainer workflow (list, review, archive, create issues) - Colored terminal output for better UX - Future-ready for API endpoint evolution Integration: - Updated CAPABILITY.yaml with feedback section - Enhanced CLAUDE.md with comprehensive integration guide - Added Makefile commands (feedback, feedback-list, feedback-stats, etc.) - Created detailed usage examples (examples/feedback-example.md) Design Philosophy: - Capability-agnostic pattern (reusable across all markitect capabilities) - Decentralized (each capability owns its feedback) - Flexible (no required formats or fields) - Durable (plain markdown files, git-tracked) - Actionable (feedback lives where maintainers work) - Scalable (works for 1 user or 1000 users) Feedback Submission Examples: ./.capability/feedback submit "Your feedback" make feedback MSG="Your feedback" echo "Feedback" > .feedback/inbound/$(date +%Y%m%d)-feedback.md Maintainer Workflow: make feedback-list # List pending make feedback-stats # Show statistics make feedback-review-issue FILE=xxx # Review and create issue This establishes a robust continuous improvement loop: User Experience → Feedback → Review → Action → Improved Capability The pattern is designed to be copied to any capability in the markitect project, providing consistent feedback collection across all capabilities. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2025-12-17 21:09:36 +01:00
parent 324453bd8d
commit 1627fd9673
6 changed files with 1274 additions and 0 deletions
--- a/.feedback/README.md
+++ b/.feedback/README.md
@@ -0,0 +1,367 @@
+# Feedback System
+
+**A lightweight, unstructured feedback loop for continuous capability improvement.**
+
+This capability uses the **feedback pattern** - a simple, reusable approach for collecting user feedback without imposing structure or process overhead.
+
+## Philosophy
+
+**Capability Owns Feedback**: Each capability maintains its own `.feedback/` directory. The capability decides how to organize, prioritize, and act on feedback.
+
+**No Structure Imposement**: Users provide feedback in whatever format works for them - quick notes, detailed reports, markdown files. The only requirement is clear communication.
+
+**Easy Submission**: One command, or just drop a file. No forms, no required fields, no process.
+
+**Maintainer Discretion**: Review and act on feedback at your own pace. Create issues, fix directly, or archive for later.
+
+## Directory Structure
+
+```
+.feedback/
+├── inbound/         # New feedback awaiting review
+├── reviewed/        # Feedback that's been reviewed (optional)
+├── archived/        # Old/resolved feedback (optional)
+└── README.md        # This file
+```
+
+**Only `inbound/` is required.** The other directories are optional organizational tools.
+
+## For Users: Submitting Feedback
+
+### Option 1: Direct File Drop (Simplest)
+
+Just create a markdown file in `.feedback/inbound/`:
+
+```bash
+cat > .feedback/inbound/$(date +%Y%m%d-%H%M%S)-my-feedback.md << 'EOF'
+## Sync Performance Issue
+
+The sync command takes 10+ minutes with 5000 issues.
+
+Would be great to have progress indicators and maybe batch processing.
+
+Thanks!
+EOF
+```
+
+### Option 2: Use Feedback CLI (If Available)
+
+Some capabilities provide a `feedback` command:
+
+```bash
+# Quick text feedback
+feedback submit "Feature request: Add bulk operations"
+
+# From file
+feedback submit my-detailed-feedback.md
+
+# With metadata
+feedback submit "Bug report" --category=bug --contact=me@email.com
+```
+
+### Option 3: From Master Project
+
+If you're integrating this capability into a master project:
+
+```bash
+cd my-master-project
+echo "Feedback about issue-facade..." > feedback.md
+
+# Copy to capability's feedback directory
+cp feedback.md capabilities/issue-facade/.feedback/inbound/$(date +%Y%m%d-%H%M%S)-sync-issue.md
+```
+
+### What to Include
+
+Whatever helps communicate your feedback:
+- Bug descriptions (steps to reproduce, error messages)
+- Feature requests (what you need, why it's valuable)
+- Performance issues (what's slow, your scale/context)
+- UX friction (what's confusing or difficult)
+- Positive notes (what's working well!)
+
+**No required format.** Just be clear.
+
+## For Maintainers: Processing Feedback
+
+### Review Workflow
+
+```bash
+# 1. List new feedback
+ls -lt .feedback/inbound/
+
+# 2. Read feedback
+cat .feedback/inbound/20251217-103045-sync-issue.md
+
+# 3. Decide action:
+#    - Create issue if it needs tracking
+#    - Fix immediately if it's quick
+#    - Document insight if it's informative
+#    - Archive if not applicable
+
+# 4. Move to reviewed/ or archived/
+mv .feedback/inbound/20251217-103045-sync-issue.md .feedback/reviewed/
+
+# 5. Optional: Add response/notes
+echo "## Maintainer Notes\n\nCreated issue #123..." >> .feedback/reviewed/20251217-103045-sync-issue.md
+```
+
+### Tracking Statistics
+
+```bash
+# Count feedback by status
+echo "Pending: $(ls .feedback/inbound/ 2>/dev/null | wc -l)"
+echo "Reviewed: $(ls .feedback/reviewed/ 2>/dev/null | wc -l)"
+echo "Archived: $(ls .feedback/archived/ 2>/dev/null | wc -l)"
+
+# Recent feedback
+ls -lt .feedback/inbound/ | head -5
+```
+
+### Creating Issues from Feedback
+
+```bash
+# Read feedback
+cat .feedback/inbound/20251217-feature-request.md
+
+# Create issue with feedback content
+issue create "Feature: Bulk label operations" \
+  --description "$(cat .feedback/inbound/20251217-feature-request.md)" \
+  --label=feedback --label=feature
+
+# Move to reviewed
+mv .feedback/inbound/20251217-feature-request.md .feedback/reviewed/
+```
+
+## Integration Patterns
+
+### Pattern 1: Standalone `.feedback/` Directory
+
+Each capability maintains its own feedback directory. Users navigate to the capability and submit feedback.
+
+```bash
+cd capabilities/issue-facade
+echo "Feedback..." > .feedback/inbound/$(date +%Y%m%d)-feedback.md
+```
+
+**Pros**: Simple, no dependencies, capability-owned
+**Cons**: Manual file creation
+
+### Pattern 2: Shared Feedback CLI
+
+Create a reusable `feedback` command that works in any capability directory:
+
+```bash
+#!/bin/bash
+# feedback - Universal feedback submission tool
+
+FEEDBACK_DIR=".feedback/inbound"
+TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+HASH=$(echo "$1" | md5sum | cut -c1-8)
+FILENAME="${FEEDBACK_DIR}/${TIMESTAMP}-${HASH}.md"
+
+# Create feedback directory if needed
+mkdir -p "$FEEDBACK_DIR"
+
+# Submit feedback
+if [ -f "$1" ]; then
+  cp "$1" "$FILENAME"
+else
+  echo "$1" > "$FILENAME"
+fi
+
+echo "Feedback submitted: $FILENAME"
+```
+
+Install once, use everywhere:
+```bash
+cp tools/feedback /usr/local/bin/feedback
+cd any-capability
+feedback "My feedback here"
+```
+
+**Pros**: Consistent UX, easy submission
+**Cons**: Requires installation
+
+### Pattern 3: Makefile Integration
+
+Add feedback commands to capability Makefile:
+
+```makefile
+.PHONY: feedback
+feedback: ## Submit feedback (Usage: make feedback MSG="your feedback")
+	@mkdir -p .feedback/inbound
+	@echo "$(MSG)" > .feedback/inbound/$$(date +%Y%m%d-%H%M%S)-feedback.md
+	@echo "Feedback submitted to .feedback/inbound/"
+
+.PHONY: feedback-list
+feedback-list: ## List pending feedback
+	@echo "Pending feedback:"
+	@ls -1t .feedback/inbound/ 2>/dev/null || echo "  (none)"
+```
+
+Usage:
+```bash
+make feedback MSG="Sync is slow with 5k issues"
+make feedback-list
+```
+
+**Pros**: No extra tools, uses existing Makefile
+**Cons**: Less flexible than CLI
+
+### Pattern 4: API Endpoint (Future)
+
+When capabilities evolve to services:
+
+```http
+POST /api/feedback
+Content-Type: application/json
+
+{
+  "content": "Feedback text...",
+  "category": "bug",
+  "contact": "user@email.com"
+}
+```
+
+Backend writes to `.feedback/inbound/` maintaining consistency with other patterns.
+
+## Metadata (Optional)
+
+While feedback content is unstructured, you *can* add metadata using front matter:
+
+```markdown
+---
+timestamp: 2025-12-17T10:30:00Z
+category: bug
+priority: high
+contact: user@example.com
+context:
+  git_repo: /path/to/master-project
+  git_branch: feature/new-sync
+  capability_version: 1.0.0
+---
+
+Actual feedback content here...
+```
+
+**Metadata is entirely optional.** Plain text/markdown works fine.
+
+## Privacy
+
+- Feedback is **anonymous by default** unless you include contact info
+- Git paths/context are for debugging, not shared externally
+- Capability maintainers see submitted feedback
+- No external tracking or telemetry
+
+## Examples
+
+**Quick Bug Report:**
+```bash
+echo "Bug: issue list crashes with --milestone='Sprint 2'" > \
+  .feedback/inbound/$(date +%Y%m%d)-crash-bug.md
+```
+
+**Detailed Feature Request:**
+```markdown
+<!-- .feedback/inbound/20251217-github-support.md -->
+
+## Feature Request: GitHub Backend
+
+**Problem**: Currently using Gitea, but our organization uses GitHub.
+
+**Proposed Solution**: Add GitHub backend similar to existing Gitea backend.
+
+**Use Case**:
+- 50+ repositories on GitHub
+- Need consistent CLI across all repos
+- Want offline sync capability
+
+**Willingness to Help**: Can test beta versions, provide GitHub API expertise.
+
+**Contact**: devteam@company.com
+```
+
+**Performance Feedback:**
+```markdown
+<!-- .feedback/inbound/20251217-sync-perf.md -->
+
+Sync performance issue:
+- 5000 issues in Gitea repo
+- `issue sync pull` takes 12 minutes
+- CPU usage is low, seems like sequential API calls
+
+Suggestion: Batch API requests or parallelize?
+
+Thanks for the great tool!
+```
+
+## For Capability Developers
+
+### Setup (5 minutes)
+
+```bash
+# 1. Create feedback directory
+mkdir -p .feedback/inbound .feedback/reviewed .feedback/archived
+
+# 2. Copy this README
+cp /path/to/feedback/template/README.md .feedback/
+
+# 3. Add to .gitignore (optional - feedback can be committed or ignored)
+echo ".feedback/inbound/*.md" >> .gitignore
+
+# 4. Document in CAPABILITY.yaml
+# Add to capabilities section:
+#   - feedback-collection
+```
+
+### Maintenance Rhythm
+
+Review feedback regularly:
+- **Daily**: Quick scan of inbound
+- **Weekly**: Deep review, create issues, respond
+- **Monthly**: Archive old feedback, analyze trends
+
+### Continuous Improvement Loop
+
+```
+User Experience → Feedback Submission → Maintainer Review →
+  → Action (Fix/Issue/Document) → Improved Capability → Better User Experience
+```
+
+The feedback loop directly informs:
+- Roadmap prioritization
+- Bug triage
+- Documentation improvements
+- UX enhancements
+
+## Rationale: Why This Pattern?
+
+**Decentralized**: Each capability owns its feedback. No central feedback system to maintain.
+
+**Flexible**: Text files are universal. No database, no service dependencies.
+
+**Durable**: Plain markdown files survive system changes, migrations, refactors.
+
+**Auditable**: Git tracks all feedback. Easy to see what was submitted when.
+
+**Actionable**: Close to the code. Maintainers see feedback where they work.
+
+**Scalable**: Works for 1 user or 1000 users. No infrastructure needed.
+
+**Future-proof**: Can evolve to CLI tools, APIs, web UIs while maintaining the same underlying structure.
+
+## This Capability's Feedback
+
+Yes, **this README itself** is part of the feedback capability pattern! If you have feedback about the feedback system:
+
+```bash
+cd capabilities/feedback  # or wherever feedback capability lives
+echo "The feedback pattern is great but..." > .feedback/inbound/$(date +%Y%m%d)-meta-feedback.md
+```
+
+We eat our own dog food. 🐕
+
+---
+
+**Thank you for using the feedback pattern. Your input shapes better capabilities.**