issue-core/.feedback

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

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:

# 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:

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

# 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

# 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

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

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:

#!/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:

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:

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

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:

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:

---
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:

echo "Bug: issue list crashes with --milestone='Sprint 2'" > \
  .feedback/inbound/$(date +%Y%m%d)-crash-bug.md

Detailed Feature Request:

<!-- .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:

<!-- .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)

# 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:

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.