coulomb/issue-core
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Projects Releases Wiki Activity

feat: implement reusable feedback capability for continuous improvement

Browse Source 
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>
This commit is contained in:
Bernd Worsch
2025-12-17 21:09:36 +01:00
parent 324453bd8d
commit 1627fd9673
6 changed files with 1274 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

391
.capability/feedback Executable file
View File

@@ -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 <filename>
#
# 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 <<EOF
---
timestamp: $timestamp
source: cli
EOF
[ -n "$category" ] && echo "category: $category"
[ -n "$contact" ] && echo "contact: $contact"
cat <<EOF
context:
git_repo: $git_repo
git_branch: $git_branch
capability_version: $cap_version
python_version: $python_version
---
EOF
}
# Submit feedback
submit_feedback() {
local content="$1"
local category="${2:-}"
local contact="${3:-}"
init_dirs
local timestamp=$(date +%Y%m%d-%H%M%S)
local hash=$(echo "$content" | md5sum 2>/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 <<EOF
feedback - Universal feedback submission tool
Usage:
feedback submit <content> [options] Submit feedback
feedback list [--reviewed|--archived] List feedback
feedback show <filename> Show specific feedback
feedback review <filename> [options] Mark feedback as reviewed (maintainers)
feedback archive <filename> Archive feedback (maintainers)
feedback stats Show feedback statistics
feedback help Show this help
Submit Options:
--category=<type> Category: bug, feature, improvement, question, other
--contact=<email> 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 <content|file> [--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 <filename>"
show_feedback "$1"
;;
review)
[ -z "${1:-}" ] && error "Usage: feedback review <filename> [--create-issue]"
review_feedback "$1" "${2:-}"
;;
archive)
[ -z "${1:-}" ] && error "Usage: feedback archive <filename>"
archive_feedback "$1"
;;
stats)
show_stats
;;
help|--help|-h)
usage
;;
*)
error "Unknown command: $command\n\n$(usage)"
;;
esac
}
main "$@"

367
.feedback/README.md Normal file
View File

@@ -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.**

40
CAPABILITY.yaml
View File

@@ -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 <filename>
./.capability/feedback review <filename> --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:

155
CLAUDE.md
View File

@@ -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.

32
Makefile
View File

@@ -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/

289
examples/feedback-example.md Normal file
View File

@@ -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 <keyword>
# Check if it's been reviewed
ls .feedback/reviewed/ | grep <keyword>
# Check if an issue was created
issue list --label=feedback --search="<your topic>"
```
## For Capability Maintainers
If you maintain this capability, see the maintainer guide:
- **Review workflow**: `.capability/feedback list` and `review`
- **Creating issues**: `.capability/feedback review <id> --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!**