[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6C0TKM9S2QP8HCVAJFHPP6M":3,"skill-same:01M6C0TKM9S2QP8HCVAJFHPP6M":87},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":28,"publishedAt":51,"linkOnly":52,"markdownContent":53,"markdownBody":54,"frontMatter":55,"refName":56,"commitSha":57,"skillDirectory":58,"forksCount":14,"repositoryHtmlUrl":59,"repositoryHomepageUrl":6,"ownerHtmlUrl":60,"ownerBlogUrl":6,"ownerDescription":61,"updatedAt":62,"install":63,"resources":76},"01M6C0TKM9S2QP8HCVAJFHPP6M","writing-standards",null,"Apply AS v2 technical-writing standards (clarity, brevity, active voice, Python\u002FDjango conventions). Use when writing a README, a docstring (PEP 257), a commit message, a PR description, an error message, or any technical doc.","matheusnorjosa\u002Faprender_sistema","matheusnorjosa","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F117673804?v=4","01M6C0S19FG12BDFBTRWY9TTEQ","Matheus Norjosa","01M6C0S1DF0YB17TKGEYC70GSP",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fmatheusnorjosa\u002Faprender_sistema\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwriting-standards\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000036","内容创作者","PROFESSION","适用职业",[29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50],"standards","writing standards","writing","README","when","docstring","brevity","technical-writing","error","as","active","message","technical","django","clarity","voice","doc","commit message","pr description","pr","commit","python","2026-11-10 10:12:30",false,"---\nname: writing-standards\ndescription: Apply AS v2 technical-writing standards (clarity, brevity, active voice, Python\u002FDjango conventions). Use when writing a README, a docstring (PEP 257), a commit message, a PR description, an error message, or any technical doc.\n---\n\n# Writing Standards — AS v2\n\nStandards for all written technical content: documentation, docstrings, commit messages, error messages, technical communication.\n\n## Core Principles\n\n### 1. Be Concise\nEvery word must earn its place. Delete redundant words (\"in order to\" → \"to\") and weak verbs (\"is able to\" → \"can\").\n\n- ❌ \"In order to check conflicts\" → ✅ \"To check conflicts\"\n- ❌ \"This function is able to validate\" → ✅ \"This function validates\"\n\n### 2. Active Voice\nPrefer active voice over passive.\n\n- ✅ \"We fixed the bug\" \u002F \"The service checks conflicts\"\n- ❌ \"The bug was fixed by us\" \u002F \"Conflicts are checked by the service\"\n\n### 3. One Idea Per Sentence\n- Write short sentences (max 25 words)\n- Each sentence expresses one clear idea\n- Complex ideas get multiple sentences\n\n**Example**:\n```\n❌ Bad (3 ideas in 1 sentence):\n\"The approval service validates permissions, logs the action\nto AuditLog, and updates the solicitação status to 'aprovado'.\"\n\n✅ Good (3 sentences):\n\"The approval service validates permissions first.\nIt logs the action to AuditLog.\nFinally, it updates the solicitação status to 'aprovado'.\"\n```\n\n### 4. Lead with Results\n- Put the outcome first\n- Make conclusions obvious\n- Don't bury the lead\n\n**Examples**:\n- ✅ \"The refactor improved performance by 40%. We optimized database queries and added caching.\"\n- ❌ \"We optimized database queries and added caching, which improved performance by 40%.\"\n\n## Naming in Writing\n\n### Descriptive Names (Python\u002FDjango)\n- Code is reference, history, and functionality\n- Names must be readable as a journal\n- Be specific and concrete\n\n**Python conventions**:\n- Functions\u002Fmethods: `snake_case` (e.g., `check_availability_conflicts`)\n- Classes: `UpperCamelCase` (e.g., `Solicitacao`, `Usuario`)\n- Constants: `SNAKE_CAPS` (e.g., `ETL_MAX_DUPLICATES_PCT`)\n\n### Avoid Vague Terms\nReplace generic terms with specific ones:\n\n- ❌ `data`, `info`, `stuff`, `manager`, `helper`, `handler`\n- ✅ `solicitacao_pendente`, `usuario_aprovador`, `municipio_origem`\n\n### Remove Redundancy\n- ✅ `users` (not `user_list` or `users_array`)\n- ✅ `approve_solicitacao()` (not `approve_solicitacao_function()`)\n\n## Documentation Standards\n\n### README Files\n**Structure** (keep under 200 lines):\n1. **What it does** (one sentence)\n2. **Why it exists** (one paragraph)\n3. **How to use it** (clear steps)\n4. **Examples** (if needed)\n5. **Link to additional docs** (if extensive)\n\n**Example**:\n```markdown\n# Availability Service\n\nChecks conflicts for solicitações following RD-01 to RD-08.\n\nThis service centralizes conflict detection logic (overlaps,\nblocks, travel buffers, daily capacity) to ensure data\nconsistency and compliance with business rules.\n\n## Usage\n\\`\\`\\`python\nfrom apps.core.services import availability_service\n\nresult = availability_service.check_conflicts(\n    usuario=formador,\n    inicio=datetime(...),\n    fim=datetime(...),\n    municipio=municipio_fortaleza\n)\n\\`\\`\\`\n\nSee [ARCHITECTURE.md](.\u002Fdocs\u002FARCHITECTURE.md) for details.\n```\n\n### Docstrings (PEP 257)\n\n**Python requires docstrings** for public functions\u002Fclasses. This is NOT optional.\n\n**Format** (Google-style):\n```python\ndef check_conflicts(\n    usuario: Usuario,\n    inicio: datetime,\n    fim: datetime,\n    municipio: Municipio\n) -> AvailabilityResult:\n    \"\"\"\n    Check availability conflicts following RD-01 to RD-08.\n\n    Args:\n        usuario: Usuario instance (formador)\n        inicio: Start datetime (aware, America\u002FFortaleza)\n        fim: End datetime (aware, America\u002FFortaleza)\n        municipio: Municipio instance for the event\n\n    Returns:\n        AvailabilityResult with list of ConflictDetail instances.\n        Empty list if no conflicts found.\n\n    Raises:\n        ValueError: If fim \u003C= inicio or timezone-naive datetimes\n    \"\"\"\n```\n\n**When to use docstrings**:\n- ✅ All public functions\u002Fmethods\n- ✅ All classes\n- ✅ Complex algorithms\n- ✅ Service layer functions\n- ❌ Private methods (optional, only if complex)\n- ❌ Obvious getters\u002Fsetters\n\n### Inline Comments (When to Use)\n\n**98% of comments should be functions\u002Fvariables**, but inline comments are useful for:\n\n1. **WHY, not WHAT**:\n   ```python\n   # PA-05: Persistent audit required for compliance\n   AuditLog.objects.create(usuario=user, action='APPROVE', ...)\n   ```\n\n2. **Business context**:\n   ```python\n   # Approvers (PA-02) may override conflicts with human context\n   # (political priorities, informal negotiations, etc.)\n   if solicitation_approval_basis(user) is not None:\n       approve_without_recheck()\n   ```\n\n3. **Gotchas\u002Fsurprises**:\n   ```python\n   # IMPORTANT: Don't use select_related here! Causes N+1 due to\n   # prefetch_related on participacoes in the next line\n   solicitacoes = Solicitacao.objects.all()\n   ```\n\n### Commit Messages\n\n**Format** (conventional commits):\n```\n\u003Ctype>(\u003Cscope>): \u003Cmessage>\n\nfeat(core): add conflict detection service (RD-01 to RD-08)\nfix(imports): handle empty CSV files in import_export_contract\ndocs(readme): update Docker setup instructions\n```\n\n**Rules**:\n- Use imperative mood (\"Add\" not \"Added\" or \"Adds\")\n- Be specific about what changed\n- Include context if not obvious\n- Max 72 characters for first line\n- **Never include \"Claude Code\"** in messages\n\n**Examples**:\n- ✅ `feat(approval): add PA-05 audit log persistence`\n- ✅ `fix(gcal): retry with exponential backoff on 429`\n- ❌ `Fixed stuff`\n- ❌ `Updates`\n- ❌ `Claude Code: Added feature`\n\n### PR Descriptions\n\n**Structure**:\n```markdown\n## What\n[One sentence describing the change]\n\n## Why\n[One paragraph explaining motivation and context]\n\n## Changes\n- [Bullet point summary of key changes]\n- [Focus on WHAT changed, not HOW]\n\n## Testing\n[How this was tested - commands run, tests added]\n\n## Compliance\n[If applicable: CP\u002FRD\u002FPA rules validated]\n```\n\n**Example**:\n```markdown\n## What\nImplements PA-05: Persistent AuditLog for approval actions.\n\n## Why\nPA-05 requires persistent audit trail (not just logger.info)\nfor compliance. Previous implementation only logged to stdout.\n\n## Changes\n- Added AuditLog.objects.create() in approve() and reject()\n- Captures: usuario, action, details, ip_address, user_agent\n- Added test_approval_flow_records_audit_log() (passing)\n\n## Testing\n\\`\\`\\`bash\npytest apps\u002Fcore\u002Ftests\u002Ftest_approval_policy_PA.py::test_approval_flow_records_audit_log -v\n# PASSED\n\\`\\`\\`\n\n## Compliance\n✅ PA-05: Persistent audit with all required fields\n```\n\n## Technical Writing\n\n### Headers\n- Short, descriptive, sentence-case\n- Make content scannable\n- Use hierarchy properly (H1 → H2 → H3)\n- Don't skip levels (H1 → H3 ❌)\n\n### Lists\n- Use for related items only\n- Keep items parallel in structure\n- Prefer prose when 2 items or less\n\n**Example**:\n```markdown\n❌ Bad (not parallel):\n- Type hints mandatory\n- You should use early returns\n- Descriptive naming\n\n✅ Good (parallel):\n- Use type hints on all functions\n- Use early returns (avoid nesting)\n- Use descriptive names (no vague terms)\n```\n\n### Examples\n- **Show, don't just tell**\n- Use real code, not pseudocode\n- Keep examples minimal and focused\n- Include expected output when helpful\n\n## Writing Anti-Patterns\n\n### Avoid\n(Conciseness and active voice are covered in Core Principles §1–§2.)\n\n- **Hedging**: \"might\", \"possibly\", \"perhaps\" (when you know the answer)\n- **Jargon without explanation**: Define terms on first use\n- **Over-explaining obvious things**: Trust the reader's intelligence\n\n### Watch For\n- Long sentences (>25 words)\n- Dense paragraphs (>5 sentences)\n- Nested clauses\n- Ambiguous pronouns (\"it\", \"this\", \"that\" without clear referent)\n\n## Specific Use Cases\n\n### Error Messages (User-Facing)\n\n**Format**: `\u003CWhat happened>. \u003CWhat to do>.`\n\n**Examples**:\n- ✅ `Solicitação not found. Check the ID and try again.`\n- ✅ `Approval failed: User lacks Superintendência permission.`\n- ✅ `Conflict detected (RD-02): Total block from 09:00 to 12:00.`\n- ❌ `An error occurred.`\n- ❌ `Something went wrong.`\n- ❌ `Error: 500` (no context)\n\n**Tone**: Helpful, not condescending. Assume intelligence, not knowledge.\n\n### API Documentation (DRF Serializers)\n\n**Include**:\n1. Purpose (one sentence)\n2. Fields (with types and constraints)\n3. Example request\u002Fresponse\n4. Error cases (if complex)\n\n**Example**:\n```python\nclass SolicitacaoSerializer(serializers.ModelSerializer[Solicitacao]):\n    \"\"\"\n    Serializer for Solicitacao model.\n\n    Read-only fields: id, created_at, meet_link\n    Required fields: projeto, municipio, inicio, fim\n    Optional fields: observacoes, is_online\n\n    Example POST request:\n    {\n        \"projeto\": 1,\n        \"municipio\": 5,\n        \"inicio\": \"2025-01-15T09:00:00-03:00\",\n        \"fim\": \"2025-01-15T12:00:00-03:00\",\n        \"observacoes\": \"Formação ACerta\",\n        \"is_online\": false\n    }\n\n    Validation errors:\n    - 400: fim \u003C= inicio\n    - 400: timezone-naive datetimes\n    - 403: User lacks permissions\n    \"\"\"\n```\n\n### Code Review Comments\n\n- Focus on code, not the person\n- Suggest alternatives, don't just criticize\n- Explain WHY, not just WHAT to change\n\n**Examples**:\n- ✅ \"Consider extracting this to a service function for testability.\"\n- ❌ \"This is wrong. Put it in a service.\"\n\n## Review Checklist\n\nBefore publishing writing:\n- [ ] Lead with the result\u002Fconclusion\n- [ ] Every sentence has one clear idea\n- [ ] Active voice used throughout\n- [ ] No redundant words\n- [ ] Specific terms (no vague language)\n- [ ] Short sentences (\u003C25 words)\n- [ ] Clear hierarchy (if using headers)\n- [ ] Examples included (if needed)\n- [ ] Scannable and skimmable\n- [ ] Docstrings follow PEP 257\n- [ ] Commit messages follow conventional commits\n\n---\n\n## References\n\n- **PEP 257**: Docstring Conventions (https:\u002F\u002Fpeps.python.org\u002Fpep-0257\u002F)\n- **Conventional Commits**: https:\u002F\u002Fwww.conventionalcommits.org\u002F\n- **ISO 9241-110**: Ergonomics principles (applies to documentation too)\n\n---\n\n**Customized for**: AS v2 (Python\u002FDjango)\n","# Writing Standards — AS v2\n\nStandards for all written technical content: documentation, docstrings, commit messages, error messages, technical communication.\n\n## Core Principles\n\n### 1. Be Concise\nEvery word must earn its place. Delete redundant words (\"in order to\" → \"to\") and weak verbs (\"is able to\" → \"can\").\n\n- ❌ \"In order to check conflicts\" → ✅ \"To check conflicts\"\n- ❌ \"This function is able to validate\" → ✅ \"This function validates\"\n\n### 2. Active Voice\nPrefer active voice over passive.\n\n- ✅ \"We fixed the bug\" \u002F \"The service checks conflicts\"\n- ❌ \"The bug was fixed by us\" \u002F \"Conflicts are checked by the service\"\n\n### 3. One Idea Per Sentence\n- Write short sentences (max 25 words)\n- Each sentence expresses one clear idea\n- Complex ideas get multiple sentences\n\n**Example**:\n```\n❌ Bad (3 ideas in 1 sentence):\n\"The approval service validates permissions, logs the action\nto AuditLog, and updates the solicitação status to 'aprovado'.\"\n\n✅ Good (3 sentences):\n\"The approval service validates permissions first.\nIt logs the action to AuditLog.\nFinally, it updates the solicitação status to 'aprovado'.\"\n```\n\n### 4. Lead with Results\n- Put the outcome first\n- Make conclusions obvious\n- Don't bury the lead\n\n**Examples**:\n- ✅ \"The refactor improved performance by 40%. We optimized database queries and added caching.\"\n- ❌ \"We optimized database queries and added caching, which improved performance by 40%.\"\n\n## Naming in Writing\n\n### Descriptive Names (Python\u002FDjango)\n- Code is reference, history, and functionality\n- Names must be readable as a journal\n- Be specific and concrete\n\n**Python conventions**:\n- Functions\u002Fmethods: `snake_case` (e.g., `check_availability_conflicts`)\n- Classes: `UpperCamelCase` (e.g., `Solicitacao`, `Usuario`)\n- Constants: `SNAKE_CAPS` (e.g., `ETL_MAX_DUPLICATES_PCT`)\n\n### Avoid Vague Terms\nReplace generic terms with specific ones:\n\n- ❌ `data`, `info`, `stuff`, `manager`, `helper`, `handler`\n- ✅ `solicitacao_pendente`, `usuario_aprovador`, `municipio_origem`\n\n### Remove Redundancy\n- ✅ `users` (not `user_list` or `users_array`)\n- ✅ `approve_solicitacao()` (not `approve_solicitacao_function()`)\n\n## Documentation Standards\n\n### README Files\n**Structure** (keep under 200 lines):\n1. **What it does** (one sentence)\n2. **Why it exists** (one paragraph)\n3. **How to use it** (clear steps)\n4. **Examples** (if needed)\n5. **Link to additional docs** (if extensive)\n\n**Example**:\n```markdown\n# Availability Service\n\nChecks conflicts for solicitações following RD-01 to RD-08.\n\nThis service centralizes conflict detection logic (overlaps,\nblocks, travel buffers, daily capacity) to ensure data\nconsistency and compliance with business rules.\n\n## Usage\n\\`\\`\\`python\nfrom apps.core.services import availability_service\n\nresult = availability_service.check_conflicts(\n    usuario=formador,\n    inicio=datetime(...),\n    fim=datetime(...),\n    municipio=municipio_fortaleza\n)\n\\`\\`\\`\n\nSee [ARCHITECTURE.md](.\u002Fdocs\u002FARCHITECTURE.md) for details.\n```\n\n### Docstrings (PEP 257)\n\n**Python requires docstrings** for public functions\u002Fclasses. This is NOT optional.\n\n**Format** (Google-style):\n```python\ndef check_conflicts(\n    usuario: Usuario,\n    inicio: datetime,\n    fim: datetime,\n    municipio: Municipio\n) -> AvailabilityResult:\n    \"\"\"\n    Check availability conflicts following RD-01 to RD-08.\n\n    Args:\n        usuario: Usuario instance (formador)\n        inicio: Start datetime (aware, America\u002FFortaleza)\n        fim: End datetime (aware, America\u002FFortaleza)\n        municipio: Municipio instance for the event\n\n    Returns:\n        AvailabilityResult with list of ConflictDetail instances.\n        Empty list if no conflicts found.\n\n    Raises:\n        ValueError: If fim \u003C= inicio or timezone-naive datetimes\n    \"\"\"\n```\n\n**When to use docstrings**:\n- ✅ All public functions\u002Fmethods\n- ✅ All classes\n- ✅ Complex algorithms\n- ✅ Service layer functions\n- ❌ Private methods (optional, only if complex)\n- ❌ Obvious getters\u002Fsetters\n\n### Inline Comments (When to Use)\n\n**98% of comments should be functions\u002Fvariables**, but inline comments are useful for:\n\n1. **WHY, not WHAT**:\n   ```python\n   # PA-05: Persistent audit required for compliance\n   AuditLog.objects.create(usuario=user, action='APPROVE', ...)\n   ```\n\n2. **Business context**:\n   ```python\n   # Approvers (PA-02) may override conflicts with human context\n   # (political priorities, informal negotiations, etc.)\n   if solicitation_approval_basis(user) is not None:\n       approve_without_recheck()\n   ```\n\n3. **Gotchas\u002Fsurprises**:\n   ```python\n   # IMPORTANT: Don't use select_related here! Causes N+1 due to\n   # prefetch_related on participacoes in the next line\n   solicitacoes = Solicitacao.objects.all()\n   ```\n\n### Commit Messages\n\n**Format** (conventional commits):\n```\n\u003Ctype>(\u003Cscope>): \u003Cmessage>\n\nfeat(core): add conflict detection service (RD-01 to RD-08)\nfix(imports): handle empty CSV files in import_export_contract\ndocs(readme): update Docker setup instructions\n```\n\n**Rules**:\n- Use imperative mood (\"Add\" not \"Added\" or \"Adds\")\n- Be specific about what changed\n- Include context if not obvious\n- Max 72 characters for first line\n- **Never include \"Claude Code\"** in messages\n\n**Examples**:\n- ✅ `feat(approval): add PA-05 audit log persistence`\n- ✅ `fix(gcal): retry with exponential backoff on 429`\n- ❌ `Fixed stuff`\n- ❌ `Updates`\n- ❌ `Claude Code: Added feature`\n\n### PR Descriptions\n\n**Structure**:\n```markdown\n## What\n[One sentence describing the change]\n\n## Why\n[One paragraph explaining motivation and context]\n\n## Changes\n- [Bullet point summary of key changes]\n- [Focus on WHAT changed, not HOW]\n\n## Testing\n[How this was tested - commands run, tests added]\n\n## Compliance\n[If applicable: CP\u002FRD\u002FPA rules validated]\n```\n\n**Example**:\n```markdown\n## What\nImplements PA-05: Persistent AuditLog for approval actions.\n\n## Why\nPA-05 requires persistent audit trail (not just logger.info)\nfor compliance. Previous implementation only logged to stdout.\n\n## Changes\n- Added AuditLog.objects.create() in approve() and reject()\n- Captures: usuario, action, details, ip_address, user_agent\n- Added test_approval_flow_records_audit_log() (passing)\n\n## Testing\n\\`\\`\\`bash\npytest apps\u002Fcore\u002Ftests\u002Ftest_approval_policy_PA.py::test_approval_flow_records_audit_log -v\n# PASSED\n\\`\\`\\`\n\n## Compliance\n✅ PA-05: Persistent audit with all required fields\n```\n\n## Technical Writing\n\n### Headers\n- Short, descriptive, sentence-case\n- Make content scannable\n- Use hierarchy properly (H1 → H2 → H3)\n- Don't skip levels (H1 → H3 ❌)\n\n### Lists\n- Use for related items only\n- Keep items parallel in structure\n- Prefer prose when 2 items or less\n\n**Example**:\n```markdown\n❌ Bad (not parallel):\n- Type hints mandatory\n- You should use early returns\n- Descriptive naming\n\n✅ Good (parallel):\n- Use type hints on all functions\n- Use early returns (avoid nesting)\n- Use descriptive names (no vague terms)\n```\n\n### Examples\n- **Show, don't just tell**\n- Use real code, not pseudocode\n- Keep examples minimal and focused\n- Include expected output when helpful\n\n## Writing Anti-Patterns\n\n### Avoid\n(Conciseness and active voice are covered in Core Principles §1–§2.)\n\n- **Hedging**: \"might\", \"possibly\", \"perhaps\" (when you know the answer)\n- **Jargon without explanation**: Define terms on first use\n- **Over-explaining obvious things**: Trust the reader's intelligence\n\n### Watch For\n- Long sentences (>25 words)\n- Dense paragraphs (>5 sentences)\n- Nested clauses\n- Ambiguous pronouns (\"it\", \"this\", \"that\" without clear referent)\n\n## Specific Use Cases\n\n### Error Messages (User-Facing)\n\n**Format**: `\u003CWhat happened>. \u003CWhat to do>.`\n\n**Examples**:\n- ✅ `Solicitação not found. Check the ID and try again.`\n- ✅ `Approval failed: User lacks Superintendência permission.`\n- ✅ `Conflict detected (RD-02): Total block from 09:00 to 12:00.`\n- ❌ `An error occurred.`\n- ❌ `Something went wrong.`\n- ❌ `Error: 500` (no context)\n\n**Tone**: Helpful, not condescending. Assume intelligence, not knowledge.\n\n### API Documentation (DRF Serializers)\n\n**Include**:\n1. Purpose (one sentence)\n2. Fields (with types and constraints)\n3. Example request\u002Fresponse\n4. Error cases (if complex)\n\n**Example**:\n```python\nclass SolicitacaoSerializer(serializers.ModelSerializer[Solicitacao]):\n    \"\"\"\n    Serializer for Solicitacao model.\n\n    Read-only fields: id, created_at, meet_link\n    Required fields: projeto, municipio, inicio, fim\n    Optional fields: observacoes, is_online\n\n    Example POST request:\n    {\n        \"projeto\": 1,\n        \"municipio\": 5,\n        \"inicio\": \"2025-01-15T09:00:00-03:00\",\n        \"fim\": \"2025-01-15T12:00:00-03:00\",\n        \"observacoes\": \"Formação ACerta\",\n        \"is_online\": false\n    }\n\n    Validation errors:\n    - 400: fim \u003C= inicio\n    - 400: timezone-naive datetimes\n    - 403: User lacks permissions\n    \"\"\"\n```\n\n### Code Review Comments\n\n- Focus on code, not the person\n- Suggest alternatives, don't just criticize\n- Explain WHY, not just WHAT to change\n\n**Examples**:\n- ✅ \"Consider extracting this to a service function for testability.\"\n- ❌ \"This is wrong. Put it in a service.\"\n\n## Review Checklist\n\nBefore publishing writing:\n- [ ] Lead with the result\u002Fconclusion\n- [ ] Every sentence has one clear idea\n- [ ] Active voice used throughout\n- [ ] No redundant words\n- [ ] Specific terms (no vague language)\n- [ ] Short sentences (\u003C25 words)\n- [ ] Clear hierarchy (if using headers)\n- [ ] Examples included (if needed)\n- [ ] Scannable and skimmable\n- [ ] Docstrings follow PEP 257\n- [ ] Commit messages follow conventional commits\n\n---\n\n## References\n\n- **PEP 257**: Docstring Conventions (https:\u002F\u002Fpeps.python.org\u002Fpep-0257\u002F)\n- **Conventional Commits**: https:\u002F\u002Fwww.conventionalcommits.org\u002F\n- **ISO 9241-110**: Ergonomics principles (applies to documentation too)\n\n---\n\n**Customized for**: AS v2 (Python\u002FDjango)\n",{"name":5,"description":7},"main","9e3a882d83e0853bdc570ae9d89c02d2a53bed82",".agents\u002Fskills\u002Fwriting-standards","https:\u002F\u002Fgithub.com\u002Fmatheusnorjosa\u002Faprender_sistema","https:\u002F\u002Fgithub.com\u002Fmatheusnorjosa","Dev Python | IA | Automation | HTML | CSS | Data | Process | Projects","2026-11-12 02:52:37",{"source":8,"skillName":5,"commands":64,"prompt":74,"zipAvailable":75},[65,68,71],{"tool":66,"command":67},"npx","npx skills add matheusnorjosa\u002Faprender_sistema --skill writing-standards",{"tool":69,"command":70},"bunx","bunx skills add matheusnorjosa\u002Faprender_sistema --skill writing-standards",{"tool":72,"command":73},"pnpm","pnpm dlx skills add matheusnorjosa\u002Faprender_sistema --skill writing-standards","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmatheusnorjosa\u002Faprender_sistema\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fwriting-standards\u002FSKILL.md",true,[77,83],{"path":78,"resourceType":79,"resourceTypeDesc":80,"sizeBytes":81,"sourceHtmlUrl":82},"checklist.md","REFERENCE","参考文档",4389,"https:\u002F\u002Fgithub.com\u002FStarksJohn\u002FCursorUserDir\u002Fblob\u002Fmain\u002Fskills\u002Fbmad-dev-story\u002Fchecklist.md",{"path":84,"resourceType":79,"resourceTypeDesc":80,"sizeBytes":85,"sourceHtmlUrl":86},"workflow.md",23320,"https:\u002F\u002Fgithub.com\u002FStarksJohn\u002FCursorUserDir\u002Fblob\u002Fmain\u002Fskills\u002Fbmad-dev-story\u002Fworkflow.md",[88,95,119,141,153,185],{"skillNo":89,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":94,"publishedAt":51},"01M6C0WHSP7S2QMJGGMQRXJ6PD","https:\u002F\u002Fgithub.com\u002Fmatheusnorjosa\u002Faprender_sistema\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fwriting-standards\u002FSKILL.md",[92,93],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},[31,30,29,50,49,48,47,46,45,44,43,42,41,32,40,39,38,37,36,35,34,33],{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":51},"01M6C0WG2SBP9PJG1YQFGGVJAR","verification-gate","Verify before claiming success. Use when about to say something works\u002Fis done, after implementing a feature, after a bugfix, or before pushing — run the proof command and confirm output first.","https:\u002F\u002Fgithub.com\u002Fmatheusnorjosa\u002Faprender_sistema\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fverification-gate\u002FSKILL.md",[],[102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,33],"verification","verification gate","gate","run","first","verify","command","use","verify before claiming","say","done","feature","proof","bugfix","output","about","implementing",{"skillNo":120,"name":121,"nameZh":6,"description":122,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":123,"categories":124,"keywords":128,"publishedAt":51},"01M6C0WE010G12KH45YZW6M7K5","test-driven-development","Write the failing test before the implementation in AS v2 (pytest + Django\u002FDRF). Use when implementing a feature or fixing a bug, before any production code is written.","https:\u002F\u002Fgithub.com\u002Fmatheusnorjosa\u002Faprender_sistema\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Ftest-driven-development\u002FSKILL.md",[125],{"categoryNo":126,"categoryName":127,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",[129,130,131,132,133,134,42,135,109,136,137,138,113,38,139,118,33,140],"test","test driven development","development","driven","code","Production","write","bug","implementation","pytest","drf","failing",{"skillNo":142,"name":143,"nameZh":6,"description":144,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":145,"categories":146,"keywords":147,"publishedAt":51},"01M6C0WC6Y81XRVBJQSTKA96XQ","subagent-development","Orquestra subagents no AS v2 — decompõe a tarefa em domínios independentes, paraleliza e revisa em 2 estágios. Use ao delegar exploração, implementação ou validação cross-arquivo para acelerar o trabalho e poupar o contexto principal.","https:\u002F\u002Fgithub.com\u002Fmatheusnorjosa\u002Faprender_sistema\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsubagent-development\u002FSKILL.md",[],[131,148,149,150,151,109,152,38],"subagent","subagent development","para","subagents","ao",{"skillNo":154,"name":155,"nameZh":6,"description":156,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":157,"categories":158,"keywords":159,"publishedAt":51},"01M6C0W9W8D6JJWXW28Q7ZHAC9","security-scan","Automated security scanning for AS v2. Use before commits or when reviewing changes for vulnerabilities. Runs dependency audit (pip-audit, npm audit), secret detection (grep patterns), and code pattern scanning (SQL injection, XSS, eval, pickle, hardcoded secrets). Integrates with project hooks system.","https:\u002F\u002Fgithub.com\u002Fmatheusnorjosa\u002Faprender_sistema\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fsecurity-scan\u002FSKILL.md",[],[160,161,162,163,164,133,165,166,167,168,169,170,171,172,173,174,175,176,109,177,178,179,38,180,181,182,183,184,33],"security","security scan","scan","vulnerabilities","sql","npm","audit","dependency audit","detection","injection","xss","secrets","pip-audit","commits","system","grep","eval","hooks","security scanning","project","with","true","pip","for","changes",{"skillNo":186,"name":187,"nameZh":6,"description":188,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":189,"categories":190,"keywords":194,"publishedAt":51},"01M6C0W7RE3G3C2852YXQKR5J9","resume-handoff","Resume work from a saved handoff document, validating its state against the current codebase before continuing. Use when resuming work from a saved handoff after a context clear or in a new session (path, session name, or GitHub issue).","https:\u002F\u002Fgithub.com\u002Fmatheusnorjosa\u002Faprender_sistema\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fresume-handoff\u002FSKILL.md",[191],{"categoryNo":192,"categoryName":193,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000038","人力资源",[195,196,197,198,199,200,201,202,203,109,204,205,206,207,208,209,210,211,33,212],"handoff","resume handoff","resume","github","state","new session","work","context","session","github issue","issue","document","clear","name","saved","codebase","resuming","new"]