From 1627fd9673194fd44dfb1b68cd8c51e43f0394ec Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 17 Dec 2025 21:09:36 +0100 Subject: [PATCH] feat: implement reusable feedback capability for continuous improvement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .capability/feedback | 391 +++++++++++++++++++++++++++++++++++ .feedback/README.md | 367 ++++++++++++++++++++++++++++++++ CAPABILITY.yaml | 40 ++++ CLAUDE.md | 155 ++++++++++++++ Makefile | 32 +++ examples/feedback-example.md | 289 ++++++++++++++++++++++++++ 6 files changed, 1274 insertions(+) create mode 100755 .capability/feedback create mode 100644 .feedback/README.md create mode 100644 examples/feedback-example.md diff --git a/.capability/feedback b/.capability/feedback new file mode 100755 index 0000000..1a4ce60 --- /dev/null +++ b/.capability/feedback @@ -0,0 +1,391 @@ +#!/usr/bin/env bash +# feedback - Universal feedback submission tool for capabilities +# +# Usage: +# feedback submit "Your feedback text" +# feedback submit path/to/feedback.md +# feedback submit "Text" --category=bug --contact=me@email.com +# feedback list [--reviewed] [--archived] +# feedback show +# +# This tool can be copied to any capability that wants to use the feedback pattern. + +set -e + +FEEDBACK_DIR=".feedback" +INBOUND_DIR="${FEEDBACK_DIR}/inbound" +REVIEWED_DIR="${FEEDBACK_DIR}/reviewed" +ARCHIVED_DIR="${FEEDBACK_DIR}/archived" + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Helper functions +error() { + echo -e "${RED}Error: $1${NC}" >&2 + exit 1 +} + +success() { + echo -e "${GREEN}$1${NC}" +} + +info() { + echo -e "${BLUE}$1${NC}" +} + +warn() { + echo -e "${YELLOW}$1${NC}" +} + +# Check if we're in a capability directory +check_capability_dir() { + if [ ! -d "$FEEDBACK_DIR" ]; then + error "Not in a capability directory with feedback support.\n Looking for: $FEEDBACK_DIR/\n Run from capability root or initialize with: mkdir -p $INBOUND_DIR" + fi +} + +# Initialize feedback directories +init_dirs() { + mkdir -p "$INBOUND_DIR" "$REVIEWED_DIR" "$ARCHIVED_DIR" +} + +# Generate metadata +generate_metadata() { + local category="${1:-}" + local contact="${2:-}" + + local timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ) + local git_repo=$(git rev-parse --show-toplevel 2>/dev/null || echo "unknown") + local git_branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown") + local python_version=$(python3 --version 2>/dev/null | cut -d' ' -f2 || echo "unknown") + + # Try to find capability version + local cap_version="unknown" + if [ -f "CAPABILITY.yaml" ]; then + cap_version=$(grep "^version:" CAPABILITY.yaml | awk '{print $2}' | tr -d '"' || echo "unknown") + fi + + cat </dev/null | cut -c1-8 || echo "$(date +%N)") + local filename="${INBOUND_DIR}/${timestamp}-${hash}.md" + + # Check if content is a file + if [ -f "$content" ]; then + info "Submitting feedback from file: $content" + { + generate_metadata "$category" "$contact" + cat "$content" + } > "$filename" + else + info "Submitting text feedback" + { + generate_metadata "$category" "$contact" + echo "$content" + } > "$filename" + fi + + success "✓ Feedback submitted: $filename" + echo "" + info "Your feedback has been recorded and will be reviewed by the capability maintainers." + echo "" + echo "To view: feedback show $(basename "$filename")" +} + +# List feedback +list_feedback() { + local dir="$INBOUND_DIR" + local label="Inbound" + + case "${1:-}" in + --reviewed) + dir="$REVIEWED_DIR" + label="Reviewed" + ;; + --archived) + dir="$ARCHIVED_DIR" + label="Archived" + ;; + esac + + check_capability_dir + + if [ ! -d "$dir" ]; then + warn "No feedback directory: $dir" + return + fi + + local count=$(ls -1 "$dir" 2>/dev/null | wc -l) + + echo -e "${BLUE}=== $label Feedback ($count) ===${NC}" + echo "" + + if [ "$count" -eq 0 ]; then + echo " (none)" + return + fi + + ls -lt "$dir" | tail -n +2 | while read -r line; do + local file=$(echo "$line" | awk '{print $NF}') + local date=$(echo "$line" | awk '{print $6, $7, $8}') + + # Try to extract category from metadata + local category="" + if [ -f "$dir/$file" ]; then + category=$(grep "^category:" "$dir/$file" | awk '{print $2}' || echo "") + fi + + # Colorize based on category + local color=$NC + case "$category" in + bug) color=$RED ;; + feature) color=$GREEN ;; + improvement) color=$YELLOW ;; + esac + + echo -e " ${color}${file}${NC}" + [ -n "$category" ] && echo " Category: $category" + echo " Date: $date" + echo "" + done +} + +# Show specific feedback +show_feedback() { + local filename="$1" + + check_capability_dir + + # Search in all directories + local filepath="" + for dir in "$INBOUND_DIR" "$REVIEWED_DIR" "$ARCHIVED_DIR"; do + if [ -f "$dir/$filename" ]; then + filepath="$dir/$filename" + break + fi + done + + if [ -z "$filepath" ]; then + error "Feedback not found: $filename" + fi + + echo -e "${BLUE}=== Feedback: $filename ===${NC}" + echo "" + cat "$filepath" +} + +# Review feedback (move to reviewed) +review_feedback() { + local filename="$1" + local create_issue="${2:-}" + + check_capability_dir + init_dirs + + if [ ! -f "$INBOUND_DIR/$filename" ]; then + error "Feedback not found in inbound: $filename" + fi + + if [ "$create_issue" = "--create-issue" ]; then + info "Creating issue from feedback..." + + # Extract title and body + local title=$(head -20 "$INBOUND_DIR/$filename" | grep -v "^---" | grep -v "^$" | head -1 | sed 's/^# *//') + local body=$(cat "$INBOUND_DIR/$filename") + + if command -v issue &> /dev/null; then + issue create "$title" --description "$body" --label=feedback + success "✓ Issue created" + else + warn "Issue command not found. Please create issue manually." + fi + fi + + mv "$INBOUND_DIR/$filename" "$REVIEWED_DIR/$filename" + success "✓ Feedback moved to reviewed: $filename" +} + +# Archive feedback +archive_feedback() { + local filename="$1" + + check_capability_dir + init_dirs + + # Try both inbound and reviewed + if [ -f "$INBOUND_DIR/$filename" ]; then + mv "$INBOUND_DIR/$filename" "$ARCHIVED_DIR/$filename" + elif [ -f "$REVIEWED_DIR/$filename" ]; then + mv "$REVIEWED_DIR/$filename" "$ARCHIVED_DIR/$filename" + else + error "Feedback not found: $filename" + fi + + success "✓ Feedback archived: $filename" +} + +# Show usage +usage() { + cat < [options] Submit feedback + feedback list [--reviewed|--archived] List feedback + feedback show Show specific feedback + feedback review [options] Mark feedback as reviewed (maintainers) + feedback archive Archive feedback (maintainers) + feedback stats Show feedback statistics + feedback help Show this help + +Submit Options: + --category= Category: bug, feature, improvement, question, other + --contact= Optional contact for follow-up + +Review Options: + --create-issue Create an issue from the feedback + +Examples: + # Quick text feedback + feedback submit "The sync command is slow with 1000+ issues" + + # Feedback from file + feedback submit my-feedback.md + + # With metadata + feedback submit "Bug: crashes on startup" --category=bug --contact=me@email.com + + # List feedback + feedback list + feedback list --reviewed + + # Show specific feedback + feedback show 20251217-103045-abc12345.md + + # Review and create issue (maintainers) + feedback review 20251217-103045-abc12345.md --create-issue + + # Archive (maintainers) + feedback archive 20251217-103045-abc12345.md + +For more information, see .feedback/README.md +EOF +} + +# Show statistics +show_stats() { + check_capability_dir + + local inbound=$(ls -1 "$INBOUND_DIR" 2>/dev/null | wc -l) + local reviewed=$(ls -1 "$REVIEWED_DIR" 2>/dev/null | wc -l) + local archived=$(ls -1 "$ARCHIVED_DIR" 2>/dev/null | wc -l) + local total=$((inbound + reviewed + archived)) + + echo -e "${BLUE}=== Feedback Statistics ===${NC}" + echo "" + echo " Pending: $inbound" + echo " Reviewed: $reviewed" + echo " Archived: $archived" + echo " ─────────────" + echo " Total: $total" + echo "" + + if [ "$inbound" -gt 0 ]; then + warn "⚠ $inbound feedback items awaiting review" + else + success "✓ No pending feedback" + fi +} + +# Main command dispatcher +main() { + local command="${1:-help}" + shift || true + + case "$command" in + submit) + local content="${1:-}" + [ -z "$content" ] && error "Usage: feedback submit [--category=TYPE] [--contact=EMAIL]" + + local category="" + local contact="" + + # Parse options + shift || true + while [ $# -gt 0 ]; do + case "$1" in + --category=*) + category="${1#--category=}" + ;; + --contact=*) + contact="${1#--contact=}" + ;; + *) + warn "Unknown option: $1" + ;; + esac + shift + done + + submit_feedback "$content" "$category" "$contact" + ;; + list) + list_feedback "$@" + ;; + show) + [ -z "${1:-}" ] && error "Usage: feedback show " + show_feedback "$1" + ;; + review) + [ -z "${1:-}" ] && error "Usage: feedback review [--create-issue]" + review_feedback "$1" "${2:-}" + ;; + archive) + [ -z "${1:-}" ] && error "Usage: feedback archive " + archive_feedback "$1" + ;; + stats) + show_stats + ;; + help|--help|-h) + usage + ;; + *) + error "Unknown command: $command\n\n$(usage)" + ;; + esac +} + +main "$@" diff --git a/.feedback/README.md b/.feedback/README.md new file mode 100644 index 0000000..a9cecbe --- /dev/null +++ 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 + + +## 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 + + +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.** diff --git a/CAPABILITY.yaml b/CAPABILITY.yaml index b3b4716..ea4c87f 100644 --- a/CAPABILITY.yaml +++ b/CAPABILITY.yaml @@ -158,12 +158,52 @@ agent_guidance: exit 1 fi +# Feedback and continuous improvement +feedback: + enabled: true + method: feedback-capability + description: > + This capability integrates the feedback pattern for continuous improvement + based on real-world usage from master projects. + + submission: + cli: ".capability/feedback submit 'Your feedback here'" + file: ".capability/feedback submit path/to/feedback.md" + directory: ".feedback/inbound/" + + organization: + inbound: "New feedback awaiting review" + reviewed: "Feedback that's been reviewed by maintainers" + archived: "Resolved or outdated feedback" + + for_users: | + Submit feedback about issue-facade: + ./.capability/feedback submit "Feedback text" + ./.capability/feedback submit detailed-feedback.md + + Or drop a file directly: + echo "Feedback..." > .feedback/inbound/$(date +%Y%m%d)-feedback.md + + for_maintainers: | + Review feedback: + ./.capability/feedback list + ./.capability/feedback show + ./.capability/feedback review --create-issue + ./.capability/feedback stats + + integration_notes: + - "Feedback capability is reusable across all markitect capabilities" + - "No structure imposement - accepts any text/markdown format" + - "Capability owns feedback organization and prioritization" + - "Can evolve to API endpoint when capability becomes a service" + # Documentation references documentation: integration: "AGENT_INTEGRATION.md" development: "CLAUDE.md" roadmap: "ROADMAP.md" examples: "examples/agents/" + feedback: ".feedback/README.md" # Dependencies and requirements requirements: diff --git a/CLAUDE.md b/CLAUDE.md index 0de2b7d..c9f0036 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -243,3 +243,158 @@ This is a capability within the larger markitect project (`/capabilities/issue-f - Can be installed independently via `pip install -e .` - Integrates with parent project via Makefile targets - Follows markitect capability conventions for structure and naming + +## Feedback and Continuous Improvement + +This capability implements the **feedback pattern** - a lightweight, unstructured feedback loop for continuous improvement based on real-world usage from master projects integrating this capability. + +### Overview + +The feedback system consists of: +- **`.feedback/` directory**: Stores all feedback with minimal organization +- **`.capability/feedback` CLI tool**: Standalone tool for submitting and managing feedback +- **No structure imposement**: Accept any text/markdown format +- **Capability-owned**: Maintainers organize and prioritize feedback + +### Directory Structure + +``` +.feedback/ +├── inbound/ # New feedback from users (unreviewed) +├── reviewed/ # Feedback reviewed by maintainers +├── archived/ # Resolved or outdated feedback +└── README.md # Complete documentation +``` + +### For Users: Submitting Feedback + +Users of issue-facade (master projects integrating it) can submit feedback in multiple ways: + +**Option 1: Using feedback CLI** +```bash +# Quick text feedback +./.capability/feedback submit "The sync command is slow with 1000+ issues" + +# From a file +./.capability/feedback submit detailed-feedback.md + +# With metadata +./.capability/feedback submit "Bug report" --category=bug --contact=me@email.com +``` + +**Option 2: Direct file drop (no CLI needed)** +```bash +# Just create a markdown file in inbound/ +cat > .feedback/inbound/$(date +%Y%m%d)-sync-issue.md << 'EOF' +The sync is taking 10+ minutes with our 5000-issue repo. +Would love to see progress indicators or batch processing. +EOF +``` + +**Option 3: From master project** +```bash +cd my-master-project +echo "Feedback about issue-facade..." > feedback.md +cp feedback.md capabilities/issue-facade/.feedback/inbound/$(date +%Y%m%d)-feedback.md +``` + +### For Maintainers: Processing Feedback + +**List and review feedback:** +```bash +# List pending feedback +./.capability/feedback list + +# Show specific feedback +./.capability/feedback show 20251217-103045-abc12345.md + +# Show statistics +./.capability/feedback stats +``` + +**Process feedback:** +```bash +# Mark as reviewed +./.capability/feedback review 20251217-103045-abc12345.md + +# Create issue from feedback +./.capability/feedback review 20251217-103045-abc12345.md --create-issue + +# Archive when resolved +./.capability/feedback archive 20251217-103045-abc12345.md +``` + +**Manual workflow (without CLI):** +```bash +# 1. List new feedback +ls -lt .feedback/inbound/ + +# 2. Read feedback +cat .feedback/inbound/20251217-103045-sync-issue.md + +# 3. Take action (create issue, fix, document) +issue create "Feature: Show sync progress" \ + --description "$(cat .feedback/inbound/20251217-103045-sync-issue.md)" \ + --label=feedback --label=feature + +# 4. Move to reviewed +mv .feedback/inbound/20251217-103045-sync-issue.md .feedback/reviewed/ +``` + +### Integration with Development Workflow + +Feedback informs: +- **Roadmap prioritization**: Most requested features get priority +- **Bug triage**: Real-world issues from production usage +- **Documentation improvements**: Where users struggle +- **UX enhancements**: Friction points in actual usage + +**Review rhythm:** +- Daily: Quick scan of new feedback +- Weekly: Deep review, create issues, respond to users +- Monthly: Archive old feedback, analyze trends + +### Feedback Pattern (Reusable Across Capabilities) + +The feedback system is **capability-agnostic** and can be copied to any markitect capability: + +1. **Copy the pattern:** + ```bash + mkdir -p .feedback/inbound .feedback/reviewed .feedback/archived + cp /path/to/feedback-template/README.md .feedback/ + cp /path/to/feedback-template/feedback .capability/ + chmod +x .capability/feedback + ``` + +2. **Document in CAPABILITY.yaml:** + ```yaml + feedback: + enabled: true + method: feedback-capability + submission: + cli: ".capability/feedback submit 'Your feedback'" + directory: ".feedback/inbound/" + ``` + +3. **Add to Makefile (optional):** + ```makefile + feedback: + @./.capability/feedback submit "$(MSG)" + ``` + +**Future Evolution:** +- When capability becomes a service, add API endpoint: `POST /api/feedback` +- API writes to same `.feedback/inbound/` directory +- Maintains consistency across CLI, file drop, and API submission + +### Why This Pattern? + +- **Decentralized**: Each capability owns its feedback +- **Flexible**: No forms, no required structure +- **Durable**: Plain files survive system changes +- **Auditable**: Git tracks all feedback +- **Actionable**: Feedback lives where maintainers work +- **Scalable**: Works for 1 user or 1000 users +- **Future-proof**: Can evolve to CLI/API while maintaining structure + +See `.feedback/README.md` for complete documentation. diff --git a/Makefile b/Makefile index 62ebc2d..a2bbf2f 100644 --- a/Makefile +++ b/Makefile @@ -38,6 +38,13 @@ help: ## Show issue facade capability help @echo " test-cov Run tests with coverage report" @echo " test-verbose Run tests with verbose output" @echo "" + @echo "Feedback & Continuous Improvement:" + @echo " feedback MSG=\"...\" Submit feedback about issue-facade" + @echo " feedback-list List pending feedback" + @echo " feedback-stats Show feedback statistics" + @echo " feedback-show FILE=\"...\" Show specific feedback" + @echo " feedback-review FILE=\"...\" Review feedback (maintainers)" + @echo "" @echo "Development & Setup (from parent):" @echo " issue-facade-install Install issue facade capability" @echo " issue-facade-install-dev Install with development dependencies" @@ -202,6 +209,31 @@ test-cov: ## Run tests with coverage report (local development) test-verbose: ## Run tests with verbose output (local development) pytest tests/ -v +# Feedback and Continuous Improvement +.PHONY: feedback +feedback: ## Submit feedback (Usage: make feedback MSG="your feedback") + @./.capability/feedback submit "$(MSG)" + +.PHONY: feedback-list +feedback-list: ## List pending feedback + @./.capability/feedback list + +.PHONY: feedback-stats +feedback-stats: ## Show feedback statistics + @./.capability/feedback stats + +.PHONY: feedback-show +feedback-show: ## Show specific feedback (Usage: make feedback-show FILE=20251217-xxx.md) + @./.capability/feedback show "$(FILE)" + +.PHONY: feedback-review +feedback-review: ## Review feedback (Usage: make feedback-review FILE=20251217-xxx.md) + @./.capability/feedback review "$(FILE)" + +.PHONY: feedback-review-issue +feedback-review-issue: ## Review feedback and create issue (Usage: make feedback-review-issue FILE=20251217-xxx.md) + @./.capability/feedback review "$(FILE)" --create-issue + .PHONY: issue-facade-install issue-facade-install: ## Install issue facade capability pip install -e capabilities/issue-facade/ diff --git a/examples/feedback-example.md b/examples/feedback-example.md new file mode 100644 index 0000000..fa2bf24 --- /dev/null +++ b/examples/feedback-example.md @@ -0,0 +1,289 @@ +# Feedback System Example + +This example demonstrates how to submit feedback about the issue-facade capability. + +## Quick Feedback Submission + +### Method 1: Using the feedback CLI + +```bash +# Navigate to the capability directory +cd capabilities/issue-facade + +# Submit quick text feedback +./.capability/feedback submit "The sync command is very slow when dealing with repositories that have 5000+ issues. Would love to see a progress indicator or batch processing to speed this up." + +# Submit detailed feedback from a file +cat > my-feedback.md << 'EOF' +## Performance Issue: Sync with Large Repositories + +**Problem**: The `issue sync pull` command takes 10+ minutes when syncing a repository with 5000+ issues. + +**Context**: +- Gitea backend +- Repository: company/large-project (5243 issues) +- Network: 100 Mbps +- System: Ubuntu 22.04, Python 3.11 + +**Observed Behavior**: +- CPU usage is low (~5%) +- Appears to be making sequential API calls +- No progress indicator, feels frozen + +**Expected Behavior**: +- Sync completes in 1-2 minutes +- Progress bar showing "Syncing: 1234/5243" +- Possibly batch API requests + +**Suggested Solutions**: +1. Parallel API requests (respect rate limits) +2. Batch endpoints (if Gitea supports them) +3. Progress indicator for UX +4. Incremental sync (only changed issues) + +**Willingness to Help**: Happy to test beta versions and provide performance metrics. + +**Contact**: devteam@company.com +EOF + +./.capability/feedback submit my-feedback.md +``` + +### Method 2: Direct File Drop (No CLI Required) + +```bash +# Just create a markdown file directly in .feedback/inbound/ +cat > .feedback/inbound/$(date +%Y%m%d-%H%M%S)-performance.md << 'EOF' +## Quick Note + +The JSON output format for `issue list` is fantastic for scripting! + +One small thing: the timestamps are in ISO format which is great, but +could we also have a `--format=json-pretty` that adds nice indentation? +Makes debugging so much easier. + +Thanks! +EOF +``` + +### Method 3: From Master Project + +If you're working in a master project that integrates issue-facade: + +```bash +# From your master project root +cd ~/my-master-project + +# Write feedback +cat > feedback-for-issue-facade.md << 'EOF' +## Feature Request: GitHub Backend + +We're using issue-facade for our Gitea repos, but our company also has +50+ repositories on GitHub. Would love to have a GitHub backend so we +can use the same CLI for all our issue tracking. + +This would enable: +- Consistent workflow across platforms +- Offline sync for GitHub issues +- Multi-repo issue searches + +We'd be happy to contribute or test! +EOF + +# Copy to capability's feedback directory +cp feedback-for-issue-facade.md \ + capabilities/issue-facade/.feedback/inbound/$(date +%Y%m%d)-github-backend.md +``` + +## Feedback Categories + +You can optionally categorize your feedback: + +```bash +# Bug report +./.capability/feedback submit "Bug: crashes when..." --category=bug + +# Feature request +./.capability/feedback submit "Please add..." --category=feature + +# Performance issue +./.capability/feedback submit "Slow performance..." --category=improvement + +# Question +./.capability/feedback submit "How do I..." --category=question + +# General feedback (no category) +./.capability/feedback submit "Great tool!" +``` + +## Including Contact Information + +If you'd like to be contacted about your feedback: + +```bash +./.capability/feedback submit "Feature request..." \ + --category=feature \ + --contact=myemail@example.com +``` + +**Note**: Contact information is optional and only used for follow-up. It's never shared externally. + +## Viewing Your Feedback + +```bash +# List all pending feedback +./.capability/feedback list + +# Show statistics +./.capability/feedback stats + +# View specific feedback +./.capability/feedback show 20251217-103045-abc12345.md +``` + +## Types of Feedback We Value + +### Bug Reports +- Describe the issue +- Steps to reproduce +- Expected vs actual behavior +- Error messages (if any) +- System/environment details + +Example: +``` +Bug: issue list crashes with certain milestone names + +Steps to reproduce: +1. issue backend add test gitea +2. issue list --milestone="Sprint 2" +3. Crashes with "AttributeError: 'NoneType' object..." + +System: macOS 14.1, Python 3.11.5, Gitea 1.21.0 +``` + +### Feature Requests +- What you need +- Why it's valuable (your use case) +- How you imagine it working +- Any alternatives you've tried + +Example: +``` +Feature Request: Bulk label operations + +Use Case: We need to relabel 200+ issues from "priority-high" to +"priority:high" (changing naming convention). + +Current Approach: Manually editing each issue (very tedious) + +Proposed: issue bulk-edit --filter="label=priority-high" \ + --remove-label=priority-high \ + --add-label=priority:high + +This would save hours of manual work. +``` + +### Performance Issues +- What's slow +- Your scale/context +- Measurements if available +- Impact on your workflow + +Example: +``` +Performance: Slow issue list with many labels + +Context: Repository with 150+ labels, 3000 issues + +Observation: `issue list` takes 8 seconds to respond + +Impact: Slows down our agent automation that polls every 30s + +Note: Local SQLite backend is instant, only Gitea backend is slow +``` + +### UX Feedback +- What's confusing or difficult +- What worked well +- Suggestions for improvement + +Example: +``` +UX: Backend configuration is confusing + +Issue: Setting up a Gitea backend required reading docs multiple times. +The prompts don't explain what URL format is expected. + +Suggestion: Show examples in the prompts: + "Gitea URL (e.g., https://gitea.example.com):" + +Also: Maybe detect from git remote and offer to auto-configure? +``` + +### Positive Feedback +We love hearing what's working well! + +Example: +``` +The offline sync feature is AMAZING! Being able to work on issues +during flights and sync later has changed my workflow completely. + +The local SQLite backend is incredibly fast and the JSON output +makes scripting so easy. + +Thank you! +``` + +## What Happens to Your Feedback + +1. **Submission**: Your feedback lands in `.feedback/inbound/` +2. **Review**: Maintainers review it (usually within a week) +3. **Action**: + - Create issue if it needs tracking + - Fix immediately if it's quick + - Document for roadmap planning + - Respond to you if you provided contact +4. **Archive**: Moved to `reviewed/` or `archived/` after handling + +## Privacy & Data + +- Feedback is **anonymous by default** +- Git paths are captured for context, not shared externally +- Contact info is only used for follow-up, never shared +- Feedback files may be committed to git (part of the project) + +## Checking Feedback Status + +If you're curious whether your feedback was addressed: + +```bash +# Check if it's still in inbound (pending review) +ls .feedback/inbound/ | grep + +# Check if it's been reviewed +ls .feedback/reviewed/ | grep + +# Check if an issue was created +issue list --label=feedback --search="" +``` + +## For Capability Maintainers + +If you maintain this capability, see the maintainer guide: +- **Review workflow**: `.capability/feedback list` and `review` +- **Creating issues**: `.capability/feedback review --create-issue` +- **Statistics**: `.capability/feedback stats` +- **Full docs**: `.feedback/README.md` + +## Questions? + +If you have questions about the feedback system itself, that's also feedback! + +```bash +./.capability/feedback submit "Question about feedback: How often is it reviewed?" +``` + +--- + +**Thank you for helping make issue-facade better through your feedback!**