Feature Enhancement Request Template: Engineering Specs

A feature enhancement request template records the exact on-screen element, its current behavior, and the requested change in a form a developer or AI agent can execute without a clarifying Slack thread. Most teams file "make the signup flow smoother" and then wonder why the wrong thing shipped.

The fix is a named element (role, label, frame), a cropped screenshot, an imperative change, and reproduction steps from a known URL or app state.

What belongs in a feature enhancement request template?

Seven fields: element identifier, current behavior, requested behavior, cropped screenshot, reproduction steps, priority, and reporter context. The identifier is what stops a request from bouncing for three sprints.

Write it as role + visible label + frame: AXButton "Continue" at (342, 518) in checkout.tsx. That maps to how macOS and browsers expose the accessibility tree, so a developer can grep the label and land on the component.

Crop the screenshot to the region. A 400x300 crop on "Continue" beats a full-screen grab where the control disappears into chrome.

Start reproduction from a URL or a known window. Web: "Go to /checkout, add SKU-4729, click Proceed." Native: "Open Preferences (⌘,), Notifications tab, Enable Alerts toggle."

Use P0 (blocks release), P1 (hurts a large segment), P2 (polish). Attach the build or commit so nobody hunts a bug that already shipped.

How do you write current and requested behavior?

Current behavior is what the element does now in testable terms. "Continue stays disabled when email is empty" works. "The button doesn't work right" does not.

Requested behavior is an instruction someone can implement. "Enable Continue when email, address, and payment are valid" works. "Make it more intuitive" does not.

Skip vague modifiers like faster or smoother. If you want a spinner, say "show a spinner inside Continue and disable it while the payment-intent call is in flight." If you want visual change, name a token: --color-primary-500, same blue as the hero CTA.

What does a complete feature enhancement request look like?

Element: AXButton "Continue" at (342, 518) in src/components/checkout/ShippingForm.tsx

Current behavior: Button stays disabled when shipping country is Canada even if every other field is valid.

Requested behavior: Enable it when email, address (postal code A1A 1A1), and payment are valid. Drop the country disable.

Screenshot: cropped crop of the disabled button, filled form, Canada selected.

Reproduction: open /checkout, add any SKU, proceed, fill a valid Canadian address and test card 4242…, watch Continue stay grey.

Priority: P1. Reporter: [email protected], 2026-08-22, v1.4.2 (a3f9c01).

A developer greps "Continue" in ShippingForm.tsx and deletes country === 'Canada'. An AI coding agent can do the same from the path plus crop.

How do you capture the element identifier without typing it?

Chrome: DevTools (⌘⌥I), element picker, Accessibility pane for role and name. Same idea in Firefox and Safari's accessibility tree view.

macOS: Accessibility Inspector (Xcode → Open Developer Tool). Click Inspect, hover, copy AXRole, AXTitle, AXFrame. Works on AppKit, SwiftUI, Electron, and many terminal UIs.

PinVari is the fast path. Hold ⌥⌘A, circle the button, say "enable this when the form is valid." It crops the region, resolves the AXButton, transcribes on-device, and files Linear, GitHub, or your AI agent over MCP. Manual typing is about two minutes. Circle-and-speak is about eight seconds.

Connect once inside the app (PinVari → Connect → Claude Code / Cursor / Codex) or with:

claude mcp add --scope user pinvari -- "$HOME/.pinvari/mcp/pinvari-mcp"

The connector talks to the running app on 127.0.0.1:3402. The agent-facing tool pinvari_next_instruction returns the path, the spoken line, the mark, and a crop. Call pinvari_mark_done when the issue is filed or the patch lands.

macOS 14+, Apple Silicon or Intel, notarized Developer-ID DMG. The Mac App Store sandbox blocks the global hotkey and reading other apps' AXUIElement, which is why it is not on the store.

What's the difference between a feature request and a bug report?

A feature request template describes something that should exist but does not. A bug report describes something that exists and behaves wrong.

Same fields, different intent. If the requested behavior is already in the spec, it is a bug. Send isolated, deterministic fixes to an AI coding agent. Send anything that needs product judgment to Linear or GitHub.

Feature enhancement request template (copyable)

**Element:** [AXRole "Label" at (x, y) in file/component]
**Current behavior:** [What happens now, in testable terms]
**Requested behavior:** [What should happen instead, as an executable instruction]
**Screenshot:** [Cropped image showing the element]
**Reproduction steps:**
1. [Starting state or URL]
2. [Each action to reach the element]
3. [Final state]
**Priority:** [P0 / P1 / P2]
**Reporter:** [Name, date, build or commit]

Comparison: manual vs assisted capture

Manual typing

Time per request: ~2 min Element accuracy: Medium (typos, wrong coordinates) Screenshot quality: Low (full-screen, not cropped) Integration: Copy/paste to Linear/GitHub

Browser DevTools + manual crop

Time per request: ~90 sec Element accuracy: High (DOM inspector shows role/label) Screenshot quality: Medium (crop in Preview) Integration: Copy/paste

macOS Accessibility Inspector + manual crop

Time per request: ~90 sec Element accuracy: High (AX API returns the values) Screenshot quality: Medium (manual crop) Integration: Copy/paste

Point-and-speak (PinVari)

Time per request: ~8 sec Element accuracy: Very high (named AX element + confidence) Screenshot quality: High (auto-cropped to the mark) Integration: Linear, GitHub, or the agent

Point-and-speak resolves the element, crops the shot, and transcribes the instruction in one gesture. Hold ⌥⌘A, circle Continue, say "enable when the form is valid." The issue body gets AXButton "Continue" at (342, 518) plus the crop. Or the AI code editor writes the fix on the next turn.

At 20 requests a week the eight-second capture is the difference between a tidy Linear board and a graveyard of uncropped PNGs in Slack. File P0s to the agent in the same breath you find them; leave P2s in the tracker for triage.

FAQ

What if the element has no accessibility label?

Describe look and position: "blue circle icon, top-right of the map canvas." Attach a crop with the mark on it. A point-and-speak tool falls back to on-device OCR when the AX tree is empty.

Can I use this template for mobile app requests?

Yes. Use the visible label and screen: "Next at the bottom of Shipping, under postal code." Start reproduction from a known screen. iOS and Android have trees, but you usually cannot inspect them without Xcode or Android Studio.

How do I handle a request that spans several screens?

Split it. One issue per element. Spinner on Continue is one ticket; API error copy is another. Link them with an epic so two people can work in parallel.

Should I include a proposed solution?

Only if you know it. "Change line 47 in validatePostalCode()" is useful. "Maybe add a regex" is not. Most product feature request templates state the outcome, not the patch.

How do you prioritize when everything feels urgent?

Score user impact against effort. P0 blocks a core flow. P1 hurts a lot of users but has a workaround. P2 is polish. A Continue button that never enables for Canada is P0. A missing hover is P2.

What's the fastest way to file one with a path and crop?

Hold ⌥⌘A in PinVari, circle the element, speak the change. It resolves role/label/frame, crops the mark, transcribes on-device, and files Linear, GitHub, or your AI agent. One-time $39 launch license. Nothing is uploaded by default.