home / skills / dropseed / plain / plain-bug

plain-bug skill

safe

This skill helps you submit Plain bug reports by collecting details and environment data, then posting to the API for quick issue tracking.

npx playbooks add skill dropseed/plain --skill plain-bug

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.4 KB

---
name: plain-bug
description: Submit a bug report for the Plain framework. Use when you encounter a bug, error, or unexpected behavior. Collects context and posts to plainframework.com.
---

# Submit a Plain Bug Report

## 1. Get bug details from the user

Ask the user for:

- **Title** (required) — a short summary of the bug
- **Body** (required) — what happened, steps to reproduce, error output, etc.

## 2. Collect environment info

Run these commands to auto-detect environment details:

```bash
uv run plain --version
```

```bash
uv run python --version
```

```bash
uname -s -r
```

## 3. Submit the bug report

POST the bug report to the Plain API using curl:

```bash
curl -s -X POST https://plainframework.com/api/issues/ \
  -H "Content-Type: application/json" \
  -d '{
    "title": "<title>",
    "body": "<body>",
    "plain_version": "<from step 2>",
    "python_version": "<from step 2>",
    "os_info": "<from step 2>"
  }'
```

## 4. Report the result

- If successful (response contains `"status": "created"`), tell the user their bug report was submitted and show the issue ID.
- If there was an error, show the error details and suggest they try again or file the issue manually on GitHub.

## Guidelines

- Always confirm the title and body with the user before submitting.
- Do NOT submit without the user's explicit approval.
- Escape special characters properly in the JSON payload.

Overview

This skill submits a bug report to the Plain framework issue API. It guides you to collect a concise title and reproducible body, auto-detects environment details, and posts the assembled report only after you confirm. You receive clear feedback with the created issue ID or error details if submission fails.

How this skill works

It asks you for a required title and body describing the bug and reproduction steps. It then runs a few commands to gather plain version, Python version, and OS info, builds a JSON payload (escaping special characters), and POSTs it to the Plain API. It shows success with the new issue ID or returns error details and next steps.

When to use it

You encounter a crash, exception, or unexpected behavior in a Plain app.
Reproducible errors or inconsistent framework behavior across environments.
When you have error output, stack traces, or clear reproduction steps.
Before filing manual issues so environment data is included automatically.
When you want a fast, consistent bug report sent to plainframework.com.

Best practices

Provide a short, specific title summarizing the observable problem.
Include minimal, reproducible steps and exact error output in the body.
Confirm the final title/body before submission — the skill will not submit without your approval.
Run the environment detection commands in the same shell/environment where the bug occurs.
Keep sensitive data out of the report; redact credentials and private tokens.

Example use cases

Reporting a crash triggered by a specific request handler with stack trace.
Submitting an error when upgrading Plain that breaks a known endpoint.
Reporting inconsistent behavior between local and CI environments.
Sending a UI rendering bug that includes request logs and reproduction steps.

FAQ

Can I edit the title or body before submission?

Yes. The skill always asks you to confirm and allows edits before sending the report.

What if the automatic environment detection fails?

You can paste plain version, Python version, and OS info manually. The skill will include whatever values you provide in the submitted payload.