Feedback

​

For

​

Use when

• A tool returns a result that contradicts another tool or the Grammar.
• An error does not say what to do next.
• Text names a tool or command that you do not have (problem tool-named-but-missing).
• Penumbra’s behaviour stops you from finishing the person’s task.
• The person asks you to tell the Penumbra team something.

​

Not this

• The person’s own data is wrong or missing: fix it in the project (card workspace).
• You want to know how to do a job: read the Grammar with penumbra grammar search "<job>".
• A change returned pending: that is not a fault (card approval).

​

Rules

1. feedback.1 Report faults in Penumbra, and nothing else. Your job: send a report when a tool, an error message or returned data is wrong or unclear. Do not send one for a refusal that Penumbra explained and that the person can fix, such as a missing permission.
2. feedback.2 Write a note a developer can act on. Your job: say what you tried, what happened and what you expected. Name the command or tool with --related "<command>" on the CLI, or related_tool on MCP. Give the request id of the reply with --about-request <request-id> on the CLI, or related_request_id on MCP. Without them, the team can only guess what you ran.
3. feedback.3 A report is a note of 1 to 5000 characters and one kind: tool, data, bug, ux, idea or other. Enforced: the API refuses a blank note, a longer note or another kind with request_invalid. The CLI refuses another --kind with invalid_option and exit code 2. Without --kind, the CLI sends other. The MCP tool needs a kind.
4. feedback.4 Keep secrets out of the note. Your job: never put a secret, File content, personal data or a customer’s confidential material in it. The report adds only the identifiers that the call already knew, such as who sent it and the project when exactly one is known. Nothing else is attached.
5. feedback.5 Mark a report as blocking only when it stops you from finishing the task. Your job: pass --blocking on the CLI, or blocking: true on MCP, for that case alone.
6. feedback.6 Any credential sends a report, with no project and no approval. Your job: do not select a project for it, and do not wait for approval. A report is never held, so a pending answer cannot come from it.
7. feedback.7 The same key files a report once. Enforced when you ask: penumbra feedback "<note>" --request-id <key> with the same note returns the same reference and files nothing again. Without the flag, the CLI makes a new key for each run, and a second run files a second report. On MCP, a retry of the same call files one report, and a new call files a new one.
8. feedback.8 Read the answer before you send again. Your job: if the answer is feedback_outcome_unknown, the CLI exits with code 4 and says that it is not a failure. Run the same command again with the same --request-id. If it is feedback_not_sent, nothing reached the team and a retry is safe. If it is feedback_unavailable, the report was not taken; tell the person and try again later.
9. feedback.9 One reporter sends at most 30 reports in an hour. Enforced: the next report is refused with rate_limited, and the answer says how many seconds to wait. Wait, and send the same command with the same key.
10. feedback.10 A report is received, not answered. Your job: tell the person that you sent it and give the reference, which starts with FDBK-. Do not say that the fault is fixed or will be fixed. Do not wait for a reply.

​

Failure signs

• Two reports for one fault: you sent it again with a new key (rule feedback.7).
• The CLI exits with code 4 after a report: rule feedback.8 and problem reply-lost.
• A report is refused with feedback_unavailable: rule feedback.8.
• The report is refused with rate_limited: rule feedback.9.

​

Doors

​

Keep going