GitHub Copilot Instructions for Problem-Based SRS

GitHub Copilot Instructions for Problem-Based SRS

Project Overview

This repository provides AgentSkills for following a Problem-Based Software Requirements Specification (SRS) methodology. The focus is on enabling AI-assisted requirements engineering through structured, problem-first approaches.

The repository follows the AgentSkills standard - an open format for giving agents new capabilities and expertise.

Core Principles

1. Problem-First Thinking: Always identify the problem before proposing solutions
2. Lightweight Methodology: Favor simplicity over complex frameworks
3. AI-Native Design: Content designed for consumption by AI agents (following AgentSkills standard)
4. Practical Guidance: Focus on actionable skills and templates

🔄 Problem-Based SRS Iteration Guidelines

Using the Methodology

When analyzing or working with this repository, use the Problem-Based SRS methodology to iterate on problems, needs, and requirements (both functional and non-functional).

Load and follow the methodology from these source files:

Artifact Naming Convention

• Customer Problems: CP.{n} or CP.{n}.{m} (e.g., CP.01, CP.01.1)
• Customer Needs: CN.{cp}.{n} (e.g., CN.01.1 traces to CP.01)
• Functional Requirements: FR.{cp}.{cn}.{n} (e.g., FR.01.1.1 traces to CN.01.1)
• Non-Functional Requirements: NFR.{version}.md (e.g., NFR.1.0.md)

Storage Location for Iterations

Save all requirement iterations in the spec/ folder:

spec/
├── README.md                    # Test suite overview
├── NFR.{version}.md             # Non-functional requirements analysis
├── static/                      # Static validation specs
├── semantic/                    # Semantic validation specs
├── integration/                 # Integration test specs
└── fixtures/                    # Test data (valid/invalid examples)

🚀 Trunk-Based Development Workflow

This repository follows trunk-based development. All changes go directly to main.

Git Workflow for Iterations

When creating or updating requirement artifacts:

git add .                                    # Stage all changes
git commit -m "<type>: <description>"        # Commit with message
git push origin main                         # Push to trunk

Commit Message Convention

Always confirm with the user before pushing to main.

Workflow Guidelines

Before Taking Action

CRITICAL: Always plan and get confirmation before executing tasks.

1. Understand the Request: Clarify what the user wants to accomplish
2. Create a Plan: Present a clear plan of what will be changed/created/deleted
3. Ask for Confirmation: Wait for user approval before executing
4. Execute: Only after confirmation, proceed with the changes
5. Verify: Show what was done and confirm completion

Example iteration workflow:

User: "Analyze the codebase and identify testing requirements"

AI: "I'll analyze using Problem-Based SRS methodology.
     Loading: skills/problem-based-srs/SKILL.md
     
     [Applies 5-step process from source files]
     
     Plan:
     1. Save analysis to spec/NFR.2.0.md
     2. git add, commit, push to main
     
     Proceed? (yes/no)"

When Working on This Repository

Skills Development (AgentSkills Format)

• Skills are located in the skills/ directory
• Each skill has a SKILL.md file with YAML frontmatter (name, description, license)
• Description field is critical - it determines when the skill triggers
• Keep SKILL.md content under 500 lines (use references/ for detailed docs)
• Follow the AgentSkills specification: https://agentskills.io/specification
• Test skills by using them in practice
• Focus on guiding users through problem identification before solution design
• Include examples that demonstrate real-world scenarios

Documentation

• Keep documentation concise and scannable
• Use markdown formatting effectively (headers, lists, code blocks)
• Provide context for why, not just what or how
• Include references to relevant SRS standards (IEEE 830, etc.) where appropriate

File Organization

• skills/: AgentSkills format (Claude Code, Claude.ai, GitHub Copilot)
  • Each skill is a self-contained directory with SKILL.md
  • Can include optional subdirectories: scripts/, references/, assets/
• docs/: Documentation, research papers, methodology guides
• docs/references/: Reference documentation for AgentSkills development
• spec/: Test specifications and requirement iterations

Code Style

• This is primarily a documentation repository
• Any code examples should be language-agnostic where possible
• Use clear, readable formatting in examples

🛠️ AgentSkills Development Guidelines

When creating or modifying skills in the skills/ directory, always follow the AgentSkills specification and best practices.

Required References

Before modifying any skill, load and follow these reference documents:

Key Requirements for Skills

SKILL.md Frontmatter (Required)

---
name: skill-name           # Max 64 chars, lowercase + hyphens only
description: What and when # Max 1024 chars, written in THIRD PERSON
license: MIT               # Optional but recommended
metadata:                  # Optional additional fields
  author: author-name
  version: "1.0"
---

Critical Rules

1. Name must match directory name - skills/my-skill/SKILL.md requires name: my-skill
2. Description in third person - "Processes files" NOT "I process files" or "You can use this"
3. Description includes WHAT and WHEN - Help agents discover when to use the skill
4. Keep SKILL.md under 500 lines - Move detailed content to references/ directory
5. File references one level deep - Don't nest reference → reference → reference

Directory Structure

skills/skill-name/
├── SKILL.md              # Required: instructions + metadata
├── references/           # Optional: detailed documentation
│   ├── guide.md
│   └── examples.md
├── scripts/              # Optional: executable code
└── assets/               # Optional: templates, resources

Skill Modification Checklist

When modifying a skill, verify:

• name field is lowercase, max 64 chars, no consecutive hyphens
• name field matches the parent directory name
• description is 1-1024 chars and written in third person
• description explains both WHAT the skill does and WHEN to use it
• SKILL.md body is under 500 lines
• Reference files are one level deep (not nested)
• Longer reference files (100+ lines) have table of contents
• No time-sensitive information in content
• Consistent terminology throughout

Example: Good vs Bad Descriptions

Good (specific, third person, includes when):

description: Orchestrates requirements engineering using the Problem-Based SRS methodology. Use when performing requirements analysis, creating customer problems, needs, or functional requirements with full traceability.

Bad (vague, first person):

description: I help with requirements.

External Resources

• Official Specification: agentskills.io/specification
• Best Practices: platform.claude.com/.../best-practices
• Example Skills: github.com/anthropics/skills

Terminology

• SRS: Software Requirements Specification
• Problem-Based: Requirements methodology that starts with problem identification
• Skill: A structured capability module designed for AI agent consumption (AgentSkills standard)
• AI Agent: Tools like GitHub Copilot, Claude Code, or similar assistants
• Trunk-Based Development: All changes committed directly to main branch

Quality Standards

• Accuracy in requirements engineering concepts
• Clarity in skill instructions
• Completeness in examples and templates
• Consistency in structure and formatting
• Traceability: Every FR traces to CN, every CN traces to CP

Quick Reference

Problem-Based SRS Commands

/cp           # Generate Customer Problems
/glance       # Create Software Glance
/cn           # Generate Customer Needs
/vision       # Build Software Vision
/fr           # Specify Functional Requirements
/zigzag       # Validate traceability
/problem-based-srs  # Full methodology orchestration

Traceability Chain

CP (WHY) → CN (WHAT) → FR (HOW)