issue-core/examples/feedback-example.md

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