On this page
Christopher Helm Creator of Wire

Wire is opinionated software. When something goes wrong, Wire should tell you clearly. When you hit a problem Wire does not catch, that is a bug worth reporting. This guide explains how to file good tickets and what happens after you do.

Before You File

1. Update Wire

Wire ships fixes continuously. Customers on pip install -e . get changes immediately. Before filing, pull and reinstall:

cd /path/to/newsroom
git pull
pip install -e .

Verify your version:

python -c "import wire; print(wire.__version__)"

If the issue disappears after updating, it was already fixed.

2. Check Open Issues

Browse existing issues before creating a new one. Your problem may already be tracked, and adding context to an existing ticket is more useful than a duplicate.

gh issue list --state open

If you find a related issue, comment on it with your site name and what you see. Even if the symptoms differ, the root cause may be the same.

3. Reproduce It

Try the exact command again. If it fails consistently, it is a real bug. If it only happened once, it may be stale bytecode, a network glitch, or a file lock.

Clear Python bytecache if you suspect stale code:

find . -name "__pycache__" -type d -exec rm -rf {} +

4. Try the Obvious Fix

Some common causes are not bugs:

  • "Command not found": Are you in the site directory (where wire.yml lives)?
  • "No API key": Is .env present with ANTHROPIC_API_KEY? Or have you run claude login for CLI-first mode?
  • "No GSC data": Have you run python -m wire.chief data at least once?
  • "Build refused": Read the error message. Wire refuses loud with a reason and usually tells you exactly what to fix.

How to File a Good Ticket

Bug Reports

A good bug report has five things:

  1. Which site. Your domain or repo path. Without this, we cannot read your config, check your database state, or reproduce the issue. Example: helm-nagel.com.

  2. What command you ran. The exact CLI command with all flags. Example: python -m wire.chief audit --lang de --topic branchen.

  3. What happened. Paste the full terminal output. Wire errors are designed to be self-explanatory. If the error message is confusing, that is also a bug.

  4. What you expected. One sentence is enough. Example: "Expected audit to show GSC data for DE pages."

  5. What you tried. So we do not suggest things you already ruled out. Example: "Ran data --lang de twice, checked .wire/gsc.db exists."

Feature Requests

A good feature request describes the pain, not the solution:

  • Bad: "Add a --fix-links flag to the build command."
  • Good: "After translating 132 pages, I have 250 lint warnings for cross-language links. Fixing them manually is not realistic."

We may solve your problem differently than you imagined. Describing the pain gives us room to find the right approach. If you have a proposed solution, include it, but lead with the problem.

What Makes a Ticket Actionable

Good Bad
"helm-nagel.com, audit --lang en shows 0 snapshots" "GSC data is missing"
"Pasted: full 20-line error output" "It crashed"
"Wire 3.9.0, ran pip install -e . today" No version info
"Tried deleting .wire/gsc.db and re-running data" "Tried everything"

What Happens After You File

Triage Process

We periodically review all open issues together. Here is what happens:

  1. We read your site. Your wire.yml, your .wire/ directory, your build output. We look at real data, not just your description.

  2. We cluster issues by root cause. If five tickets describe symptoms of the same architectural gap, we file one architectural fix that addresses all of them. Your ticket stays open for its remaining scope.

  3. We comment on your ticket. You will see one of:

    • "Update from #N": An architectural fix partially addresses your issue. We explain what changes and what remains.
    • "Covered by #N": Your issue is fully addressed by another ticket. We close yours with an explanation.
    • "Refined scope": Your issue is valid but we adjusted the approach. We explain why.

  4. We write an execution roadmap. Issues get ordered by dependency. Some must land before others. We post the order so you know what comes first.

What You Can Expect

  • Every ticket gets a response. Even if the answer is "this is not a Wire problem."
  • Root cause over symptoms. We may not fix your exact request, but we will fix the underlying problem.
  • Your data informs the fix. We test with your actual site, not just the dogfood site. If it works on our site but breaks on yours, that is a Wire bug.
  • Transparent decisions. If we close your ticket, we explain why. If we change the approach, we explain why.

What We Ask of You

  • One issue per problem. Do not bundle unrelated problems into one ticket. "Build crashes AND the footer is ugly" is two issues.
  • Comment if things change. If you find a workaround, if the problem gets worse, if you have new context, comment on the ticket. Stale tickets get deprioritized.
  • Update Wire before commenting "still broken." We ship fixes between triage rounds. Pull, reinstall, retry.

Filing from the Command Line

If you use the GitHub CLI:

# Bug report
gh issue create --title "issue: build crashes on German pages with tabs shortcode" \
  --body "Site: helm-nagel.com
Command: python -m wire.build
Expected: Clean build
Actual: KeyError on line 2450
Version: 3.9.0
Tried: Removed tabs shortcode from one page — build passes"

# Feature request
gh issue create --title "feat: auto-fix cross-language links after translation" \
  --body "Site: helm-nagel.com
Problem: 250 RULE-36 warnings after translating DE pages. All are mechanical link rewrites.
Workaround: None — fixing 250 links manually across 132 files is not realistic."

GitHub Issue Templates

When you create an issue on GitHub, you will see structured templates for bug reports and feature requests. These templates enforce the fields above so nothing gets missed. Use them.