Add Standard

Add Standard

Create and add a new code standard to the code-standards package.

When to Use

Use this skill when:

• "Add a standard for..."
• "Create a coding standard..."
• "Document a new convention..."
• "Add guidance for..."

Workflow

1. Check for Existing Standards

Before creating a new standard, always check if one already exists:

PREFIX cs: <http://pragma.canonical.com/codestandards#>

SELECT ?standard ?description WHERE {
  ?standard a cs:CodeStandard ;
            cs:description ?description .
  FILTER(CONTAINS(LCASE(STR(?standard)), "your-topic"))
}

Or use lookup:

sem_lookup(type: "cs:CodeStandard", filters: {"@id": {"$contains": "your-topic"}})

2. Determine the Category

List existing categories to find the right fit:

PREFIX cs: <http://pragma.canonical.com/codestandards#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?category ?label ?slug WHERE {
  ?category a cs:Category ;
            rdfs:label ?label ;
            cs:slug ?slug .
}

Available Categories:

If no existing category fits, create a new one (see Section 5).

3. Design the Standard Identifier

Standard identifiers follow a hierarchical compact IRI pattern: cs:{category}.{domain}.{topic}

Pattern: ^cs:[a-z]+(\.[a-z0-9_]+){2,}$

Examples:

• cs:react.component.structure.folder
• cs:css.selectors.namespace
• cs:styling.tokens.creation
• cs:react.hooks.naming

Guidelines:

• Use lowercase with underscores for multi-word segments
• Category is always the first segment after cs:
• Be specific but not overly verbose
• Follow existing naming patterns in the same category
• Treat the subject IRI as the only canonical identifier
• Use cs:name only for an optional human-readable display title

4. Write the Standard

Create a new standard instance in the appropriate data file under data/.

Template:

cs:category.domain.topic a cs:CodeStandard ;
    cs:name "Human Readable Title" ;
    cs:hasCategory cs:category ;
    cs:description "Clear, concise description of what this standard covers and why it matters." ;
    cs:do [
        cs:description "First recommended practice." ;
        cs:language "typescript" ;
        cs:code """
// Example showing the correct approach
const good = true;
    """
    ] ;
    cs:do [
        cs:description "Second recommended practice." ;
        cs:language "typescript" ;
        cs:code """
// Another correct example
const alsoGood = true;
    """
    ] ;
    cs:dont [
        cs:description "First anti-pattern to avoid." ;
        cs:language "typescript" ;
        cs:code """
// Example showing what NOT to do
const bad = true;
    """
    ] ;
    cs:dont [
        cs:description "Second anti-pattern." ;
        cs:language "typescript" ;
        cs:code """
// Another bad example
const alsoBad = true;
    """
    ] .

Each cs:do and cs:dont is a blank node (cs:Example) with structured fields:

• cs:description — What the example demonstrates (required)
• cs:language — Language of the code block, e.g. "typescript", "rust", "css", "bash", "svg" (optional, omit when no code)
• cs:code — The code content (optional, omit for description-only examples)

Required Properties:

• subject IRI - Canonical compact identifier
• cs:hasCategory - Reference to a Category instance
• cs:description - What and why (plain text or markdown)
• cs:do - One or more positive examples (blank nodes)
• cs:dont - One or more negative examples (blank nodes)

Optional Properties:

• cs:name - Human-readable display title
• cs:extends - Reference to a parent standard this builds upon

5. Create a New Category (if needed)

If your standard doesn't fit existing categories:

cs:new_category a cs:Category ;
    rdfs:label "Category Name"@en ;
    rdfs:comment "Description of what this category covers"@en ;
    cs:slug "slug-name" .

6. Extending Existing Standards

When your standard builds on another:

cs:react.component.props.special_case a cs:CodeStandard ;
    cs:name "React Props Special Case" ;
    cs:extends cs:react.component.props ;
    cs:hasCategory cs:react ;
    cs:description "Specific guidance that builds on the general props standard." ;
    cs:do [
        cs:description "Example of the specific pattern." ;
        cs:language "typescript" ;
        cs:code """
// ...
    """
    ] ;
    cs:dont [
        cs:description "Anti-pattern to avoid." ;
        cs:language "typescript" ;
        cs:code """
// ...
    """
    ] .

Query to find potential parent standards:

PREFIX cs: <http://pragma.canonical.com/codestandards#>

SELECT ?standard WHERE {
  ?standard a cs:CodeStandard .
  FILTER(STRSTARTS(STR(?standard), STR(cs:react.component.props)))
}

7. Validate Before Committing

After writing the standard, validate the Turtle syntax:

sem check code-standards

Then verify the standard loads correctly:

sem_lookup(type: "cs:CodeStandard", filters: {"@id": "cs:category.domain.topic"})

The @id must always use the canonical compact IRI. Do not look up standards by cs:name.

File Organization

Standards are organized by category in data/:

code-standards/
├── definitions/
│   └── CodeStandard.ttl    # Ontology schema
├── data/
│   ├── react.ttl           # React standards
│   ├── css.ttl             # CSS standards
│   ├── styling.ttl         # Styling standards
│   ├── code.ttl            # General code standards
│   ├── storybook.ttl       # Storybook standards
│   └── icons.ttl           # Icon standards
└── skills/
    └── standards-guide/
        └── SKILL.md

Add new standards to the file matching their category.

Writing Quality Standards

Description Guidelines

• Start with WHAT the standard covers
• Explain WHY it matters
• Keep it concise but complete
• Use markdown for complex descriptions

Do Examples Guidelines

• Each cs:do blank node is one discrete positive example
• cs:description explains what the example demonstrates
• cs:language must match the code block language (e.g. "typescript", "css", "rust")
• cs:code contains the actual code — no markdown fences needed
• Provide concrete, runnable examples
• Show the COMPLETE correct pattern

Don't Examples Guidelines

• Each cs:dont blank node is one discrete negative example
• Show realistic mistakes developers make
• cs:description should explain WHY it's problematic
• Mirror the structure of the do examples where possible

Example Quality Checklist

• Examples are syntactically correct
• Examples are self-contained (can be understood without context)
• Examples use realistic code, not foo/bar
• Examples include comments explaining key points
• Both do's and don'ts cover the same scenarios

Complete Example

Adding a new standard for React error boundaries:

# In data/react.ttl

cs:react.component.error_boundaries a cs:CodeStandard ;
    cs:name "React Error Boundaries" ;
    cs:hasCategory cs:react ;
    cs:description "Error boundaries must be used to catch JavaScript errors in component trees and display fallback UI. They should be placed strategically to isolate failures without breaking the entire application." ;
    cs:do [
        cs:description "Wrap feature sections with error boundaries to isolate failures." ;
        cs:language "tsx" ;
        cs:code """
const Dashboard = () => (
  <div className="ds dashboard">
    <ErrorBoundary fallback={<WidgetError />}>
      <AnalyticsWidget />
    </ErrorBoundary>
    <ErrorBoundary fallback={<WidgetError />}>
      <ActivityWidget />
    </ErrorBoundary>
  </div>
);
    """
    ] ;
    cs:do [
        cs:description "Provide meaningful fallback UI that helps users understand and recover." ;
        cs:language "tsx" ;
        cs:code """
const WidgetError = () => (
  <div className="ds widget-error">
    <p>This section couldn't load.</p>
    <button => window.location.reload()}>
      Refresh page
    </button>
  </div>
);
    """
    ] ;
    cs:dont [
        cs:description "Wrap the entire application in a single error boundary." ;
        cs:language "tsx" ;
        cs:code """
// Bad: One error anywhere crashes everything
const App = () => (
  <ErrorBoundary>
    <Header />
    <Main />
    <Footer />
  </ErrorBoundary>
);
    """
    ] ;
    cs:dont [
        cs:description "Use generic or unhelpful fallback messages." ;
        cs:language "tsx" ;
        cs:code """
// Bad: Doesn't help the user
const fallback = <div>Something went wrong</div>;
    """
    ] .

Tips

1. Check before creating: Always search for existing standards first - you might need to extend rather than create new
2. Follow patterns: Look at existing standards in the same category for style guidance
3. Be specific: Vague standards are hard to follow - include concrete examples
4. Test your examples: Make sure code examples actually work
5. Consider hierarchy: Use cs:extends when your standard builds on another