issue-core/.feedback/README.md

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