ENG-2105 Add shared engineering writing style skill to the repo - #1278
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
This pull request has been ignored for the connected project Preview Branches by Supabase. |
mdroidian
assigned
maparent,
sid597 and
trangdoan982 and unassigned
maparent,
sid597 and
trangdoan982
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c3046a5e93
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - Prefer the shortest version that remains clear and preserves necessary nuance. | ||
| - Use natural contractions and everyday wording. Avoid corporate jargon, inflated phrasing, and generic professional filler. | ||
| - Avoid em dashes as sentence-level punctuation. Use a period, comma, colon, semicolon, or parentheses to separate thoughts instead. Preserve em dashes only when they appear in exact quotations, titles, source text, or technical content supplied by the requester. | ||
| - Keep warmth light: use a brief greeting, thanks, or friendly closing when appropriate, without extended pleasantries. |
There was a problem hiding this comment.
I think Adapt to the Channel section covers it
There was a problem hiding this comment.
Could you clarify what "it" is referring to here? Are you suggesting we remove this line?
There was a problem hiding this comment.
I agree that "for a quick reply or chat message" below is a narrower context than stated in this line. Not sure I'd even allow greetings or thanks.
There was a problem hiding this comment.
This was co-opted from a general writing style that applied to many situations. It could still apply, but likely to be rare. I'll remove it.
| - For a quick reply or chat message, omit the greeting and sign-off when they add no value. | ||
| - For technical issues, describe the observed behavior, the relevant contrast or expectation, and the requested clarification or next step. | ||
|
|
||
| ## Drafting rules |
There was a problem hiding this comment.
Who is the requester in this section? is it the dev working with agent or a reviewer?
I think the skill should be on a team level and individuals can have their own drafting rules and different weightage, otherwise this will silently be changing the workflow on an individual level.
There was a problem hiding this comment.
The 'requester' means the developer asking the agent to draft or revise something.
The goal of this skill is to give our team-facing writing a consistent voice and style. It shouldn't define or change anyone's workflow. While I'd be open for separate individual drafting layers, I'd first be curious to see what situation would use it.
Could you point to where you see it directing workflow, or give an example of an individual rule you'd want to layer on top?
trangdoan982
left a comment
trangdoan982
left a comment
There was a problem hiding this comment.
lgtm. I wholeheartedly agree with the Core styles but not sure how the Drafting rules will help with my use cases. but open to try it out first then twitch the prompt if needed
maparent
left a comment
maparent
left a comment
There was a problem hiding this comment.
I would add a high-level directive about helping the author identify anything that is ambiguous, or can be misconstrued.
| - Prefer the shortest version that remains clear and preserves necessary nuance. | ||
| - Use natural contractions and everyday wording. Avoid corporate jargon, inflated phrasing, and generic professional filler. | ||
| - Avoid em dashes as sentence-level punctuation. Use a period, comma, colon, semicolon, or parentheses to separate thoughts instead. Preserve em dashes only when they appear in exact quotations, titles, source text, or technical content supplied by the requester. | ||
| - Keep warmth light: use a brief greeting, thanks, or friendly closing when appropriate, without extended pleasantries. |
There was a problem hiding this comment.
I agree that "for a quick reply or chat message" below is a narrower context than stated in this line. Not sure I'd even allow greetings or thanks.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 08f6a05b69
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…al documentation and clarify usage for team communication.
4 participants
Summary
$discourse-engineering-writing-styleskill to the repository.Why
The skill was only available locally. Adding it under
skills/makes the same concise engineering writing guidance available to the team and keeps it version-controlled.Validation
quick_validate.py skills/discourse-engineering-writing-stylepnpm exec prettier --check skills/discourse-engineering-writing-style/SKILL.md skills/discourse-engineering-writing-style/agents/openai.yamlpolicy.productsuses the schema-supportedCHATandCODEXvalues.Scope check
$scope-checkagainst ENG-2105 and the final diff.Done When: None.