# GitHub Copilot Instructions for Problem-Based SRS > This repository provides AgentSkills for following a Problem-Based Software Requirements Specification (SRS) methodology. - Skill: `tools-only/github-copilot-instructions-for-problem-based-srs` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/github-copilot-instructions-for-problem-based-srs` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/github-copilot-instructions-for-problem-based-srs/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-29 - Page: https://skillmd.com/skills/tools-only/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](https://agentskills.io)** 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:** | Step | Skill Reference | |------|-----------------| | 1. Customer Problems (WHY) | `skills/problem-based-srs/references/step1-customer-problems.md` | | 2. Software Glance | `skills/problem-based-srs/references/step2-software-glance.md` | | 3. Customer Needs (WHAT) | `skills/problem-based-srs/references/step3-customer-needs.md` | | 4. Software Vision | `skills/problem-based-srs/references/step4-software-vision.md` | | 5. Functional Requirements (HOW) | `skills/problem-based-srs/references/step5-functional-requirements.md` | | Validation | `skills/problem-based-srs/references/zigzag-validator.md` | | Orchestrator | `skills/problem-based-srs/SKILL.md` | ### 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: ```bash git add . # Stage all changes git commit -m ": " # Commit with message git push origin main # Push to trunk ``` ### Commit Message Convention | Prefix | Use Case | Example | |--------|----------|---------| | `feat:` | New feature or requirement | `feat: Add CP.02 for mobile access` | | `fix:` | Bug fix or correction | `fix: Correct FR.01.2.1 traceability` | | `docs:` | Documentation updates | `docs: Update README with new workflow` | | `spec:` | Test specifications | `spec: Add traceability validation tests` | | `refactor:` | Restructuring without changing behavior | `refactor: Reorganize spec folder` | **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:** | Reference | Path | Purpose | |-----------|------|---------| | **Specification** | `docs/references/agentskills-specification.md` | SKILL.md format, required fields, directory structure | | **Best Practices** | `docs/references/agentskills-best-practices.md` | Content organization, naming, descriptions, patterns | ### Key Requirements for Skills #### SKILL.md Frontmatter (Required) ```yaml --- 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):** ```yaml 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):** ```yaml description: I help with requirements. ``` ### External Resources - **Official Specification**: [agentskills.io/specification](https://agentskills.io/specification) - **Best Practices**: [platform.claude.com/.../best-practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) - **Example Skills**: [github.com/anthropics/skills](https://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)