SMART POLE Coding Agent Skill
This Skill implements the SMART POLE framework adapted for AI Coding Agents. Unlike the chatbot versions (Instructor/Enforcer), this skill operates on codebases — scanning project files, extracting context automatically, and ensuring the agent has enough information before writing code.
How to Load This Skill
- Set system prompt: Load
references/system-prompt.md as the agent's system prompt (e.g., paste into AGENTS.md, .claude/system_prompt.md, or the agent's system role configuration).
- Provide reference files: Make
references/logic.md, references/overlap-rules.md, and references/coding-agent-categories.md available in the agent's context or knowledge base.
- Invoke: Give the agent a vague or specific coding task. The agent will ORIENT (scan the codebase), CLASSIFY the task type, EXTRACT SP-categories, and check execution gates before touching any file.
Reference Files
| File |
Purpose |
references/system-prompt.md |
🔴 Required — Full Coding Agent system prompt (v4.0). Load as the agent's system instructions. |
references/logic.md |
Framework logic: category definitions, weighted scoring, task-type classification, generic-to-coding task mapping. |
references/overlap-rules.md |
Atom overlap rules, conflict detection, Functional Gravity principle, and the One Atom One Slot rule. |
references/coding-agent-categories.md |
Code-native sub-dimensions for all 9 SP-categories with auto-detection sources and hard-stop gate definitions. |
When to Use This Skill
- A user gives a vague coding task ("fix the login bug", "add pagination")
- Before an agent starts multi-file code changes
- When a task involves unfamiliar parts of a codebase
- Migration or refactoring tasks where scope control is critical
How It Works
- ORIENT: Agent scans project root (
README.md, AGENTS.md, package.json, Dockerfile, etc.)
- CLASSIFY: Determine task type (Bug Fix / Feature / Refactor / Migration / Infra)
- EXTRACT: Map request to 9 code-native SP-categories
- DETECT FLAWS: Identify missing context, overlaps, and conflicts; ask user if critical
- PLAN: Create implementation plan with file-level scope
- EXECUTE: Apply file changes within approved scope
- VERIFY: Run tests, lint, type-check; self-heal on failures
The 9 Code-Native Categories
| Abbrev |
Category |
Code Meaning |
Priority |
| S |
Style |
Code standards, linting, architecture pattern |
🟢 Auto-detect |
| M |
Mastery |
Developer expertise level — split into Domain vs Task (see below) |
🟡 Contextualizer |
| A |
Aim |
Definition of Done, acceptance criteria, success metric |
🔴 CORE |
| R |
Resource |
Allowed/forbidden deps, API quotas, team contacts, internal docs |
🟡 Contextualizer |
| T |
Time |
Deadline, urgency level (hotfix vs long-term), sprint constraints |
🟢 Accelerator |
| P |
People |
Team conventions, reviewer persona, implicit values & preferences |
🟡 Contextualizer |
| O |
Outline |
Authorized file scope, folder boundaries, what NOT to touch |
🔴 CORE |
| L |
Locale |
Runtime ecosystem, language/framework version, legal/infra constraints |
🟡/🔴 CONDITIONAL |
| E |
Example |
Reference code snippets, similar PRs, anti-pattern stories |
🟡/🟢 CONDITIONAL |
Category Deep-Dives (SP-Flaw Prevention)
⏱️ T — Time: Urgency Only, Not Quality
T answers: "How much time do I have?" — deadline, sprint slot, hotfix vs planned refactor.
⚠️ T-Flaw (Category Overlap): Do NOT put acceptance criteria or content depth requirements inside T.
- ❌ Wrong:
T: "Must be thorough enough to not need follow-up" ← this is an A-atom
- ✅ Right:
T: "Hotfix — must ship in 2 hours" / T: "Non-urgent — next sprint"
Quality gates and success criteria belong in Aim (A) or Outline (O), not Time.
👥 P — People: Make Implicit Traits Explicit
P answers: "Who is involved and what are their hidden assumptions?"
Beyond team conventions, always surface:
- Reviewer Persona: Does the reviewer prioritize security over speed? Hate over-engineered abstractions?
- Implicit Values: Prefers functional style? Allergic to ORMs? Values minimal diffs?
- Psychological traits: Team culture (consensus-driven vs individual autonomy), risk tolerance
⚠️ P-Flaw (Implicit People): Do NOT leave personality traits and values implicit — the agent will guess wrong.
- ❌ Wrong: Omitting that the team hates
any types in TypeScript
- ✅ Right:
P: "Reviewer flags every use of 'any' in TypeScript — use strict types always"
🎓 M — Mastery: Always Split Domain vs Task
M answers: "What does the developer know — and in which dimension?"
Always decompose Mastery into two parts:
| Dimension |
Meaning |
Example |
| M-Domain |
Expertise in tech stack / role |
Senior React, Junior DevOps |
| M-Task |
Experience with this specific task type |
Never integrated Stripe before, First time with WebSocket |
⚠️ M-Flaw (Mastery Scope): Missing the gap between Domain and Task mastery causes the agent to pitch solutions that are technically fluent but practically inappropriate.
- ❌ Wrong:
M: "Senior Developer" ← domain only, no task dimension
- ✅ Right:
M-Domain: "Senior React" | M-Task: "Novice — first time implementing OAuth2 flow" → agent uses familiar React patterns but explains OAuth2 step-by-step
🧰 R — Resource: Tools + People + Data
R answers: "What weapons do I have — and what is forbidden?"
Resource includes three dimensions, not just software:
| Dimension |
Examples |
| Tools |
Allowed libs/frameworks, CI/CD pipeline, dev environment |
| People / Network |
Team members who can review, external consultants, on-call SMEs |
| Data / Docs |
Internal wikis, API docs, log access (/var/log/auth.log), Sentry |
⚠️ R-Flaw (Resource Underutilization): Listing only software tools leaves the agent unable to suggest "ask the security team" or "check the Confluence runbook."
- ❌ Wrong:
R: "Jira, Notion" ← tools only
- ✅ Right:
R-Tools: "Jira" | R-Network: "Security team available for review" | R-Data: "Sentry logs + Redis CLI access"
Also supply Negative Atoms (what is forbidden):
R-Forbidden: "No new npm deps without approval, no changes to DB schema"
📌 E — Example: The Anchor Atom
E answers: "What should the output look like — concretely?"
In coding context, a Gold Standard E-atom is a matched pair:
| E-atom Type |
What it looks like |
| Code snippet |
Before/after code block showing the pattern to follow |
| Similar PR |
Link or description of a past PR that solved a comparable bug |
| Input/Output pair |
Expected test case: input state → expected behavior |
| Anti-example (Story) |
"Last time we did X this way, it broke Y — avoid this pattern" |
⚠️ E-Flaw (Missing Anchor): Without an Example atom, the agent mimics its training data defaults, not your codebase conventions.
- ❌ Weak:
E: "Make it look clean" ← too vague, gives agent no anchor
- ✅ Gold:
E: "Follow the pattern in auth_service.py:L45–80 — token invalidation before session update" or E: "This Sentry trace shows the failure chain: A→B→C"
Always ask: "Is there a similar PR, a log trace, or a code section I want the agent to mimic?"
Auto-Extraction Sources
| Source File |
SP-Categories Extracted |
.eslintrc / ruff.toml |
S (Style) |
package.json / pyproject.toml |
R (Resource), L (Locale) |
Dockerfile / docker-compose.yml |
L (Locale), R (Resource) |
AGENTS.md / SKILL.md |
P (People), S (Style) |
CI/CD configs (.github/workflows/) |
R (Resource), A (Aim quality gates) |
Coding Task Classification
| Task Type |
Primary SP-cats |
Agent Behavior |
| Bug Fix |
A, E, O |
Minimal change + regression test |
| Feature |
A, O, R |
Plan → implement → test |
| Refactor |
O, E, P |
Preserve behavior, improve structure |
| Migration |
L, R, T |
Incremental, backward compatible |
| Infra |
L, R, A |
Infrastructure as Code, idempotent |
Task Taxonomy Mapping (Generic → Coding)
Use this mapping to bridge generic SMART POLE task types in references/logic.md with coding-agent task types.
Generic Task Type (references/logic.md) |
Coding Task Type(s) |
Default Interpretation |
| Deterministic |
Bug Fix, Refactor |
Behavior is constrained; prioritize reproducibility and regression tests |
| Generative |
Feature |
New capability; prioritize clear DoD and explicit scope boundaries |
| Advisory |
Refactor, Migration, Infra |
Architecture/process guidance; convert advice into testable acceptance criteria before coding |
| Discovery |
Feature (spike), Migration (assessment) |
Exploration is allowed, but execution stays minimal and reversible |
| Compliance |
Infra, Migration, Bug Fix |
Regulatory/security constraints are first-class acceptance criteria |
Execution Gates (Hard Stops)
Do not execute code changes until all hard-stop gates pass:
- Gate A (Aim): At least one testable acceptance criterion exists.
- Gate O (Outline): Authorized scope is explicit (or defaults to minimal scope) and forbidden scope is respected.
- Gate Conflict: All
SP-conflict items are resolved by user decision.
- Gate Overlap: Apply
One Atom, One Slot from references/overlap-rules.md; no double-counted atoms.
- Gate Score: Weighted readiness score is >= 67% of the applicable max score (per
references/logic.md task-type weighting).
If any gate fails:
- Stop before
EXECUTE
- Ask targeted clarification questions
- Re-plan only after user confirmation
Worked Example: Bug Fix Context Extraction
User request: "Fix the login bug — users can't login after password reset"
| SP-cat |
Atom |
Why here, not elsewhere |
| S |
Auto-detect from .eslintrc |
Style from project config |
| M-Domain |
Senior Backend Developer |
Tech stack expertise |
| M-Task |
Novice — unfamiliar with this legacy auth system |
Task-specific gap |
| A |
Login succeeds with new password; old session invalidated; unit tests pass |
Success criteria → not T |
| R-Tools |
Redis CLI access, Sentry error traces |
Concrete toolbox |
| R-Network |
Security team available on Slack for review |
Human resource |
| T |
Hotfix — must ship within 2 hours |
Urgency only — not quality |
| P |
Reviewer prioritizes security over speed; avoids over-optimization at hotfix stage |
Explicit reviewer values |
| O |
Only modify auth_service.py and password_controller.py |
Scope boundary |
| L |
Python 3.11, Django 4.2, Redis 7 |
Runtime ecosystem |
| E |
Sentry trace shows: PasswordReset→UpdateDB→[FAIL: session not invalidated]→Login |
Concrete anchor |
🔍 SP-flaw check: "Write unit tests" is an A-atom (acceptance criterion), NOT a T-atom (time/urgency).
Key Differences from Chatbot Versions
| Aspect |
Instructor/Enforcer |
Coding Agent |
| Output |
Master Prompt text |
Working code + passing tests |
| Reasoning visibility |
Prompt-analysis oriented |
Concise decisions tied to files/tests (no explicit CoT requirement) |
| Verification |
User reviews prompt |
Agent runs tests automatically |
| Context |
Conversation only |
Codebase + configs + file system |
| Self-healing |
N/A |
Auto-fix on test failure (max 3 attempts) |
Optional: Integration with Other Skills
This skill works best as a pre-flight layer in any coding agent workflow, ensuring sufficient context before execution begins. Pair with project-specific AGENTS.md or workflow files.
1---2name: sp-coding-agent3description: Use when a coding task is vague or under-specified. Extracts missing context across 9 code-native categories before the agent executes file changes. Designed for OpenAI Codex, Anthropic Claude Code, and Google Gemini Code Assist.4---56# SMART POLE Coding Agent Skill78This Skill implements the **SMART POLE** framework adapted for **AI Coding Agents**. Unlike the chatbot versions (Instructor/Enforcer), this skill operates on **codebases** — scanning project files, extracting context automatically, and ensuring the agent has enough information before writing code.910---1112## How to Load This Skill13141. **Set system prompt**: Load `references/system-prompt.md` as the agent's system prompt (e.g., paste into `AGENTS.md`, `.claude/system_prompt.md`, or the agent's system role configuration).152. **Provide reference files**: Make `references/logic.md`, `references/overlap-rules.md`, and `references/coding-agent-categories.md` available in the agent's context or knowledge base.163. **Invoke**: Give the agent a vague or specific coding task. The agent will ORIENT (scan the codebase), CLASSIFY the task type, EXTRACT SP-categories, and check execution gates before touching any file.1718---1920## Reference Files2122| File | Purpose |23|------|---------|24| `references/system-prompt.md` | 🔴 **Required** — Full Coding Agent system prompt (v4.0). Load as the agent's system instructions. |25| `references/logic.md` | Framework logic: category definitions, weighted scoring, task-type classification, generic-to-coding task mapping. |26| `references/overlap-rules.md` | Atom overlap rules, conflict detection, Functional Gravity principle, and the One Atom One Slot rule. |27| `references/coding-agent-categories.md` | Code-native sub-dimensions for all 9 SP-categories with auto-detection sources and hard-stop gate definitions. |2829---3031## When to Use This Skill3233- A user gives a vague coding task ("fix the login bug", "add pagination")34- Before an agent starts multi-file code changes35- When a task involves unfamiliar parts of a codebase36- Migration or refactoring tasks where scope control is critical3738## How It Works39401. **ORIENT**: Agent scans project root (`README.md`, `AGENTS.md`, `package.json`, `Dockerfile`, etc.)412. **CLASSIFY**: Determine task type (Bug Fix / Feature / Refactor / Migration / Infra)423. **EXTRACT**: Map request to 9 code-native SP-categories434. **DETECT FLAWS**: Identify missing context, overlaps, and conflicts; ask user if critical445. **PLAN**: Create implementation plan with file-level scope456. **EXECUTE**: Apply file changes within approved scope467. **VERIFY**: Run tests, lint, type-check; self-heal on failures4748## The 9 Code-Native Categories4950| Abbrev | Category | Code Meaning | Priority |51| --- | --- | --- | --- |52| **S** | Style | Code standards, linting, architecture pattern | 🟢 Auto-detect |53| **M** | Mastery | Developer expertise level — split into Domain vs Task (see below) | 🟡 Contextualizer |54| **A** | Aim | Definition of Done, acceptance criteria, success metric | 🔴 **CORE** |55| **R** | Resource | Allowed/forbidden deps, API quotas, team contacts, internal docs | 🟡 Contextualizer |56| **T** | Time | Deadline, urgency level (hotfix vs long-term), sprint constraints | 🟢 Accelerator |57| **P** | People | Team conventions, reviewer persona, implicit values & preferences | 🟡 Contextualizer |58| **O** | Outline | Authorized file scope, folder boundaries, what NOT to touch | 🔴 **CORE** |59| **L** | Locale | Runtime ecosystem, language/framework version, legal/infra constraints | 🟡/🔴 **CONDITIONAL** |60| **E** | Example | Reference code snippets, similar PRs, anti-pattern stories | 🟡/🟢 **CONDITIONAL** |6162---6364### Category Deep-Dives (SP-Flaw Prevention)6566#### ⏱️ T — Time: Urgency Only, Not Quality6768**T answers**: "How much time do I have?" — deadline, sprint slot, hotfix vs planned refactor.6970> ⚠️ **T-Flaw (Category Overlap)**: Do NOT put acceptance criteria or content depth requirements inside T.71>72> - ❌ Wrong: `T: "Must be thorough enough to not need follow-up"` ← this is an **A-atom**73> - ✅ Right: `T: "Hotfix — must ship in 2 hours"` / `T: "Non-urgent — next sprint"`7475Quality gates and success criteria belong in **Aim (A)** or **Outline (O)**, not Time.7677---7879#### 👥 P — People: Make Implicit Traits Explicit8081**P answers**: "Who is involved and what are their hidden assumptions?"8283Beyond team conventions, always surface:8485- **Reviewer Persona**: Does the reviewer prioritize security over speed? Hate over-engineered abstractions?86- **Implicit Values**: Prefers functional style? Allergic to ORMs? Values minimal diffs?87- **Psychological traits**: Team culture (consensus-driven vs individual autonomy), risk tolerance8889> ⚠️ **P-Flaw (Implicit People)**: Do NOT leave personality traits and values implicit — the agent will guess wrong.90>91> - ❌ Wrong: Omitting that the team hates `any` types in TypeScript92> - ✅ Right: `P: "Reviewer flags every use of 'any' in TypeScript — use strict types always"`9394---9596#### 🎓 M — Mastery: Always Split Domain vs Task9798**M answers**: "What does the developer know — and in which dimension?"99100Always decompose Mastery into **two parts**:101102| Dimension | Meaning | Example |103|-----------|---------|---------|104| **M-Domain** | Expertise in tech stack / role | Senior React, Junior DevOps |105| **M-Task** | Experience with this specific task type | Never integrated Stripe before, First time with WebSocket |106107> ⚠️ **M-Flaw (Mastery Scope)**: Missing the gap between Domain and Task mastery causes the agent to pitch solutions that are technically fluent but practically inappropriate.108>109> - ❌ Wrong: `M: "Senior Developer"` ← domain only, no task dimension110> - ✅ Right: `M-Domain: "Senior React" | M-Task: "Novice — first time implementing OAuth2 flow"` → agent uses familiar React patterns but explains OAuth2 step-by-step111112---113114#### 🧰 R — Resource: Tools + People + Data115116**R answers**: "What weapons do I have — and what is forbidden?"117118Resource includes **three dimensions**, not just software:119120| Dimension | Examples |121|-----------|---------|122| **Tools** | Allowed libs/frameworks, CI/CD pipeline, dev environment |123| **People / Network** | Team members who can review, external consultants, on-call SMEs |124| **Data / Docs** | Internal wikis, API docs, log access (`/var/log/auth.log`), Sentry |125126> ⚠️ **R-Flaw (Resource Underutilization)**: Listing only software tools leaves the agent unable to suggest "ask the security team" or "check the Confluence runbook."127>128> - ❌ Wrong: `R: "Jira, Notion"` ← tools only129> - ✅ Right: `R-Tools: "Jira" | R-Network: "Security team available for review" | R-Data: "Sentry logs + Redis CLI access"`130131Also supply **Negative Atoms** (what is forbidden):132> `R-Forbidden: "No new npm deps without approval, no changes to DB schema"`133134---135136#### 📌 E — Example: The Anchor Atom137138**E answers**: "What should the output look like — concretely?"139140In coding context, a **Gold Standard E-atom** is a matched pair:141142| E-atom Type | What it looks like |143|-------------|-------------------|144| **Code snippet** | Before/after code block showing the pattern to follow |145| **Similar PR** | Link or description of a past PR that solved a comparable bug |146| **Input/Output pair** | Expected test case: input state → expected behavior |147| **Anti-example (Story)** | "Last time we did X this way, it broke Y — avoid this pattern" |148149> ⚠️ **E-Flaw (Missing Anchor)**: Without an Example atom, the agent mimics its training data defaults, not your codebase conventions.150>151> - ❌ Weak: `E: "Make it look clean"` ← too vague, gives agent no anchor152> - ✅ Gold: `E: "Follow the pattern in auth_service.py:L45–80 — token invalidation before session update"` or `E: "This Sentry trace shows the failure chain: A→B→C"`153154Always ask: *"Is there a similar PR, a log trace, or a code section I want the agent to mimic?"*155156---157158### Auto-Extraction Sources159160| Source File | SP-Categories Extracted |161|-------------|------------------------|162| `.eslintrc` / `ruff.toml` | **S** (Style) |163| `package.json` / `pyproject.toml` | **R** (Resource), **L** (Locale) |164| `Dockerfile` / `docker-compose.yml` | **L** (Locale), **R** (Resource) |165| `AGENTS.md` / `SKILL.md` | **P** (People), **S** (Style) |166| CI/CD configs (`.github/workflows/`) | **R** (Resource), **A** (Aim quality gates) |167168## Coding Task Classification169170| Task Type | Primary SP-cats | Agent Behavior |171|-----------|----------------|----------------|172| Bug Fix | A, E, O | Minimal change + regression test |173| Feature | A, O, R | Plan → implement → test |174| Refactor | O, E, P | Preserve behavior, improve structure |175| Migration | L, R, T | Incremental, backward compatible |176| Infra | L, R, A | Infrastructure as Code, idempotent |177178## Task Taxonomy Mapping (Generic → Coding)179180Use this mapping to bridge generic SMART POLE task types in `references/logic.md` with coding-agent task types.181182| Generic Task Type (`references/logic.md`) | Coding Task Type(s) | Default Interpretation |183|-----------|----------------|----------------|184| Deterministic | Bug Fix, Refactor | Behavior is constrained; prioritize reproducibility and regression tests |185| Generative | Feature | New capability; prioritize clear DoD and explicit scope boundaries |186| Advisory | Refactor, Migration, Infra | Architecture/process guidance; convert advice into testable acceptance criteria before coding |187| Discovery | Feature (spike), Migration (assessment) | Exploration is allowed, but execution stays minimal and reversible |188| Compliance | Infra, Migration, Bug Fix | Regulatory/security constraints are first-class acceptance criteria |189190## Execution Gates (Hard Stops)191192Do not execute code changes until all hard-stop gates pass:1931941. **Gate A (Aim)**: At least one testable acceptance criterion exists.1952. **Gate O (Outline)**: Authorized scope is explicit (or defaults to minimal scope) and forbidden scope is respected.1963. **Gate Conflict**: All `SP-conflict` items are resolved by user decision.1974. **Gate Overlap**: Apply `One Atom, One Slot` from `references/overlap-rules.md`; no double-counted atoms.1985. **Gate Score**: Weighted readiness score is **>= 67%** of the applicable max score (per `references/logic.md` task-type weighting).199200If any gate fails:201202- Stop before `EXECUTE`203- Ask targeted clarification questions204- Re-plan only after user confirmation205206## Worked Example: Bug Fix Context Extraction207208**User request**: `"Fix the login bug — users can't login after password reset"`209210| SP-cat | Atom | Why here, not elsewhere |211|--------|------|------------------------|212| **S** | `Auto-detect from .eslintrc` | Style from project config |213| **M-Domain** | `Senior Backend Developer` | Tech stack expertise |214| **M-Task** | `Novice — unfamiliar with this legacy auth system` | Task-specific gap |215| **A** | `Login succeeds with new password; old session invalidated; unit tests pass` | Success criteria → **not** T |216| **R-Tools** | `Redis CLI access, Sentry error traces` | Concrete toolbox |217| **R-Network** | `Security team available on Slack for review` | Human resource |218| **T** | `Hotfix — must ship within 2 hours` | Urgency only — **not** quality |219| **P** | `Reviewer prioritizes security over speed; avoids over-optimization at hotfix stage` | Explicit reviewer values |220| **O** | `Only modify auth_service.py and password_controller.py` | Scope boundary |221| **L** | `Python 3.11, Django 4.2, Redis 7` | Runtime ecosystem |222| **E** | `Sentry trace shows: PasswordReset→UpdateDB→[FAIL: session not invalidated]→Login` | Concrete anchor |223224> 🔍 **SP-flaw check**: "Write unit tests" is an **A-atom** (acceptance criterion), NOT a **T-atom** (time/urgency).225226## Key Differences from Chatbot Versions227228| Aspect | Instructor/Enforcer | Coding Agent |229|--------|-------------------|--------------| 230| Output | Master Prompt text | Working code + passing tests |231| Reasoning visibility | Prompt-analysis oriented | Concise decisions tied to files/tests (no explicit CoT requirement) |232| Verification | User reviews prompt | Agent runs tests automatically |233| Context | Conversation only | Codebase + configs + file system |234| Self-healing | N/A | Auto-fix on test failure (max 3 attempts) |235236## Optional: Integration with Other Skills237238This skill works best as a **pre-flight layer** in any coding agent workflow, ensuring sufficient context before execution begins. Pair with project-specific `AGENTS.md` or workflow files.
cuongpt083