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

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!**