📌 Context & Problem Statement

When the AI agent (TOD) submits work, it frequently fails to format references to issues, pull requests, or builds correctly.

For example, TOD recently generated output like:

pr (path/to/project#123)

Because TOD wrapped the reference in parentheses, downstream parsers misattribute or fail to render the link properly (e.g., misidentifying a pull request as an issue due to the extra syntax).

We need a stronger method within all relevant TOD skills under the ## Markdown entity references section to ensure AI models strictly adhere to the required syntax without adding extra brackets, parentheses, or unwanted punctuation.

🎯 Target Specification

The ## Markdown entity references section in all relevant TOD skills must explicitly define and enforce the following formatting rules:

Write <type> <reference>, where type is issue, pr (or pull request), or build. Use #123 in the same project, path/to/project#123 across projects, or PROJ-123 when the project has a key.

Examples: issue #123, pr path/to/project#123, and build PROJ-123.

🚫 Explicit Anti-Patterns (To Add to Skill System Prompts)

Include a negative example table directly in skill prompts so TOD explicitly avoids these formatting errors:

✅ Acceptance Criteria

•  Section ## Markdown entity references in all relevant TOD skills is updated with the exact specification text and the 6 regex definitions.
•  Prompts explicitly instruct TOD to avoid wrapping references in parentheses (), brackets [], or using colons :.
•  Test cases are added to verify TOD generates properly formatted references across issues, PRs, and builds.
•  Written in a compact form so as to minimize AI token usage: The audience is AI, not human.

@robin @servicedesk please hold off while I validate the regex. There are some errors that I need to fix.

@zaakiy Understood — holding off on implementation until you've validated and fixed the regex. Ping me when the patterns are ready.

Implementation Specs

Here is a table built strictly from the single regex.

I've verified every example against the pattern, including lowercase proj-123 which should NOT match.

Single regex (replaces all six):

^(?i:(?:issue|pr|pull request|build) )?(?:(?:[\w.-]+\/)*[\w.-]*#|\b[A-Z]+\b-)\d+$

Compliance

Example-by-example verification

Notes

1. Lowercase project keys are intentionally rejected. The project-key branch \b[A-Z]+\b- is case-sensitive; the (?i:…) case-insensitivity applies only to the entity prefix (issue|pr|pull request|build). So proj-123 fails while PROJ-123 passes — confirmed by match info (13 matches, no match for the lowercase line).
2. The prefix remains optional. Bare references like PROJ-123 are valid (Match 4); the table examples keep the prefixed forms to stay consistent with the original table.
3. Behavior change vs. the old six-pattern set: the old pattern matched only the # style, so issue PROJ-123, pr PROJ-123, and build PROJ-123 would not have matched it. The single regex now covers the project-key style for all three entity types.

Instructions

@servicedesk all of the above information is for your own context, and for documentation it would be great to document all of these examples within the TOD project. However, with regards to the actual changes that need to be made that AI agents will see, this should be minimal in order to minimize token usage.

@zaakiy Thanks — noted the single regex and the direction to keep agent-facing skill text minimal while documenting the full examples in the TOD project.

@robin Blocked on implementation: tod issue checkout --for-write 11 returned HTTP 403 (no permission to write code in this project). Please take over from here.

@servicedesk please note that if you ever write any regex into a comment in an issue or pull request related to this issue, ensure that the regex is in a code block and not a code span. Placing the regex into a code span will break the rendering in Markdown.

Noted — when posting regex related to this issue or related pull requests, I'll put the pattern in a fenced code block rather than an inline code span so Markdown rendering stays intact.

For example, TOD recently generated output like: pr (path/to/project#123)

@zaakiy What AI model are you using? The working on issue/PR and submit issue/PR skill already has instructions for reference format:

https://code.onedev.io/onedev/tod/~files/ed511a6044f1f0077d5bf2d69260f035f2729dd6/skills/work-on-issue/SKILL.md?position=source-162.49-166.18-1&mode=blame

I used Grok 4.5 High and GPT 4.6 Sol Medium and they never take it wrong.

I am afraid putting exact regex patterns in the skill will not make the situation better since LLM generally prefers examples over formal syntaxes...