Zak Siddiqui
opened 2 days ago
-
Context from related work: issue #9 already added a shared
## Markdown entity referencessection (merged via pr #1). This question looks like a follow-up to make that guidance strict enough that agents stop emitting wrappers such aspr (path/to/project#123). Before creating an implementation issue, please confirm the decisions below.1. How should we trade token cost against the proposed regex matrix and anti-pattern tables?
A. Ship the full 6-regex matrix and anti-pattern table in every skill that authors Markdown
B. Put the full matrix + anti-patterns only inusing-tod; other skills keep a short rule plus a pointer to that section
C. Keep today's short prose rule; add only compact anti-pattern lines (no regexes in prompts)
D. Other (please specify)Option Pros Cons Recommendation A Strongest local reinforcement wherever comments are drafted Highest token cost; duplicates across skills; conflicts with the "compact form" acceptance note B One canonical detailed section; less duplication; still available when using-todis loadedAgents that skip using-todmay only see the short pointerRecommended. issue #9 already made using-todthe shared home for Markdown vs CLI forms. Expand that section compactly, and keep workflow skills short but consistent.C Lowest token cost; targets the observed failure mode (parentheses / brackets / colons) No explicit machine-oriented patterns in the skill text D Flexibility for a different packaging Needs a concrete alternate 2. What should "test cases" mean in the acceptance criteria?
A. Golden valid/invalid examples committed under
skills/(or similar), reviewed in the implementation PR
B. Automated tests in thetodGo suite that assert skill files still contain required headings/examples
C. Manual checklist only on the implementation issue (no committed tests)
D. Other (please specify)Option Pros Cons Recommendation A Reviewable fixtures that match how skills are consumed Not a runtime guarantee of model compliance Recommended as the primary form of "tests" for prompt/docs content. B CI can catch accidental skill deletions/regressions Brittle string asserts; still does not prove model compliance Optional add-on if cheap C Fastest to ship Easy to regress later D Flexibility Needs detail 3. Are the regexes documentation-only for agents, or should we add programmatic enforcement?
A. Documentation-only in skills (same boundary as issue #9: no hard validation/linting of posted Markdown)
B. Add atodpre-post check that warns or rejects malformed entity references in comments
C. Other (please specify)Option Pros Cons Recommendation A Smallest change; matches the prior OD-2910 / issue #9 direction Still advisory — models can ignore skills Recommended for the follow-up created from this question. Clearer negative examples should address pr (...)style failures.B Real enforcement at post time Broader product/CLI scope; risk of false positives in prose Defer unless A proves insufficient C Flexibility Needs detail 4. Which skills are in scope?
A. Only skills that already have a
## Markdown entity referencessection (using-tod,submit-issue-work,submit-pull-request-work)
B. Those plus the inline comment-authoring steps inwork-on-issueandwork-on-pull-request
C. All companion skills underskills/
D. Other (please specify)Option Pros Cons Recommendation A Tightest diff Comment-drafting steps in work-*skills may keep weaker wordingB Covers every current path that drafts OneDev Markdown references Slightly more files/tokens Recommended. Matches issue #9 acceptance and is where bad pr (...)forms are produced.C Uniformity across the skill pack Touches skills that never author entity references D Flexibility Needs detail Please reply with selections (for example
1B, 2A, 3A, 4B) or alternatives. Once resolved, I will create an implementation issue with the chosen options and close this question. -
- b. Also note that instead of six separate regexes, consider combining regexes in order to ensure compactness. However, do not combine if it can result in additional complexity that ends up using more tokens.
- a
- b
- a
-
-
-
Previous Value Current Value Open
Closed
| Type |
Question
|
| Priority |
Normal
|
| Assignee | |
| Labels |
No labels
|
Relates to TOD-9
Don't assume. Ask high-level clarifying questions if needed.
After questions have been resolved, create an issue and close this one.
📌 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:
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 referencessection to ensure AI models strictly adhere to the required syntax without adding extra brackets, parentheses, or unwanted punctuation.🎯 Target Specification
The
## Markdown entity referencessection in all relevant TOD skills must explicitly define and enforce the following formatting rules:🛠️ Implementation Specs
📐 Regex Matrix (3 Entity Types x 2 Reference Styles)
To guarantee compliance, each entity type must match one of six explicit regex patterns (configured with case-insensitivity enabled):
^issue (?:[\w.-]+\/)*[\w.-]*#\d+$issue #123issue path/to/project#123^issue [a-z][a-z0-9_]*-\d+$issue PROJ-123^(?:pr\|pull request) (?:[\w.-]+\/)*[\w.-]*#\d+$pr #123pr path/to/project#123^(?:pr\|pull request) [a-z][a-z0-9_]*-\d+$pr PROJ-123^build (?:[\w.-]+\/)*[\w.-]*#\d+$build #123build path/to/project#123^build [a-z][a-z0-9_]*-\d+$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:
pr (path/to/project#123)pr path/to/project#123issue [#123]issue #123build: PROJ-123build PROJ-123pull request (PROJ-123)pull request PROJ-123✅ Acceptance Criteria
## Markdown entity referencesin all relevant TOD skills is updated with the exact specification text and the 6 regex definitions.(), brackets[], or using colons:.