agile-v-behavioral

Agile V Behavioral Guidelines

Anti-pattern prevention for Agile V agents. Combines proven behavioral guidelines with Agile V traceability to prevent common LLM failures.

Companion skill: Load agile-v-core first. This skill extends core directives with behavioral safeguards.

Tradeoff: These guidelines bias toward caution and clarity over speed. For trivial single-REQ implementations, use judgment.

---

1. Think Before Coding (Enhanced for Agile V)

Don't assume. Don't hide confusion. Surface tradeoffs. Document decisions.

Before REQ Synthesis

• State assumptions explicitly in Decision Log before implementation
• If REQ has multiple interpretations, halt and present options (don't pick silently)
• If simpler approach exists, document trade-off in Decision Log
• If REQ is unclear, invoke Requirement Architect or Logic Gatekeeper (don't improvise)

Integration with Agile V

• Halt Condition (Directive #6): If requirement is ambiguous, stop. Name what's confusing. Ask.
• Decision Log: Every interpretation choice → DECISION_LOG.md entry with timestamp, rationale, alternatives considered
• REQ Clarification Protocol: Don't implement vague requirements; send back for refinement

Example:

REQ-0042: "Improve error handling"

❌ Don't: Silently add try/catch blocks everywhere
✅ Do: Halt and ask:
  - "Improve" how? (user-facing messages? logging? retry logic?)
  - Which error scenarios? (network? validation? unexpected data?)
  - What's acceptable error UX? (fail silently? show message? redirect?)

Then log decision:
DECISION: Add validation error handling with user-facing messages
RATIONALE: User reported confusing silent failures on form submission
LINKED_REQ: REQ-0042 (refined to REQ-0042a: validation error UX)

---

2. Simplicity First (Enhanced for Agile V)

Minimum code that satisfies REQ acceptance criteria. Nothing speculative.

No Features Beyond REQ Scope

• No features beyond approved REQ-XXXX acceptance criteria
• No abstractions for single-use code unless REQ explicitly requires extensibility
• No "flexibility" or "configurability" that wasn't in REQ acceptance criteria
• No error handling for impossible scenarios (stay within REQ constraints)
• If you write 200 lines and it could be 50, rewrite it

Ask yourself: "Would a senior engineer call this overcomplicated?" If yes, simplify.

Integration with Agile V

• Artifact Traceability: Every ART-XXXX links to exactly one REQ-XXXX. If code doesn't map to REQ acceptance criteria, it's out of scope.
• Speculative Features: If you think a feature might be useful but it's not in a REQ, document as CR proposal, don't implement.
• Multi-Cycle Discipline: Don't add "nice-to-haves" during implementation. Flag for next cycle.

Example:

# ❌ Over-engineered for single REQ
# REQ-0010: Calculate 10% discount on orders over $100

class DiscountStrategy(ABC):
    @abstractmethod
    def calculate(self, amount: float) -> float: pass

class PercentageDiscount(DiscountStrategy): ...
class TieredDiscount(DiscountStrategy): ...
class ConfigurableDiscountEngine: ...

# ✅ Simple, traceable to REQ-0010
# ART-0010: Discount calculation
# Implements: REQ-0010 (10% discount on orders >$100)

def calculate_discount(order_total):
    """REQ-0010: 10% discount for orders over $100."""
    if order_total > 100:
        return order_total * 0.10
    return 0.0

When abstraction IS warranted:

• ≥2 distinct REQs require the same pattern → justify abstraction with REQ-IDs
• Example: REQ-0010 (discount), REQ-0015 (shipping calc), REQ-0020 (tax calc) all need pricing rules → abstraction justified. Document in Decision Log.

---

3. Surgical Changes (Enhanced for Multi-Cycle)

Touch only what changed REQs require. Clean up only your own mess.

When Editing Existing Artifacts

• Don't "improve" adjacent code unless it's linked to a changed REQ or CR
• Don't refactor things that aren't broken (no drive-by optimizations)
• Match existing style, even if you'd do it differently (consistency > preference)
• If you notice unrelated dead code, log as OBS-XXXX (observation), don't delete

When Your Changes Create Orphans

• Remove imports/variables/functions that YOUR CR made unused (document in CR)
• Don't remove pre-existing dead code unless CR explicitly scopes it

Integration with Agile V

• Multi-Cycle Discipline: In Cycle 2+, only modify artifacts linked to new or modified REQs or active CRs
• Change Request Scope: Every line changed should trace to a CR-XXXX. If it doesn't, it's out of scope.
• Regression Prevention: Surgical changes → fewer unexpected regressions → faster Red Team verification

The Test: Every changed line should trace directly to a REQ-XXXX or CR-XXXX. If not, revert it.

Example:

Cycle 2: CR-0005 requires changing password validation (REQ-0002)

# ❌ Scope creep
def validate_password(password):
    # Changed per CR-0005
    if len(password) > 128:
        return False, "Max 128 chars"
    
    # UNRELATED: Reformatted entire function, fixed typo in adjacent comment,
    # "improved" variable naming in unrelated login() function

# ✅ Surgical
def validate_password(password):
    # CR-0005: Add max length validation
    if len(password) > 128:
        return False, "Password must be 128 characters or less"
    
    # (rest of function unchanged)

---

4. Goal-Driven Execution (Enhanced for Red Team Protocol)

Transform REQ acceptance criteria into TC-XXXX. Success = TC passes, not "code runs."

REQ → Verifiable Goals

Every REQ acceptance criterion becomes a test case:

• "Add validation" → TC-XXXX: Invalid inputs rejected with specific error messages
• "Fix the bug" → TC-XXXX: Reproduce bug, verify fix, ensure no regression
• "Refactor X" → TC-XXXX: All existing tests pass before and after

Integration with Agile V

• Red Team Protocol (Directive #4): Build Agent does not verify own work
• Test Designer Parallel Execution: TC-XXXX created from REQ-XXXX only (independent of ART-XXXX)
• Auto-Fix Loop: If Red Team finds failures, max 3 attempts, then escalate to Human Gate

For Multi-Step Synthesis: State a brief plan with verification checkpoints:

REQ-0025: User profile update with avatar upload

Build Plan:
1. Create upload endpoint → verify: TC-0025-01 (accepts valid image)
2. Add image validation → verify: TC-0025-02 (rejects invalid files)
3. Save to storage → verify: TC-0025-03 (file persisted, URL returned)
4. Update user record → verify: TC-0025-04 (DB reflects new avatar)
5. Integration test → verify: TC-0025-05 (end-to-end flow)

Weak vs Strong Success Criteria:

Weak (avoid)	Strong (use)
"Make it work"	"TC-0025-01 passes: Valid JPEG upload returns 200 + URL"
"Add tests"	"TC-0025-02: Rejects files >5MB with 413 error"
"Improve performance"	"TC-0025-06: Upload completes in <2s for 1MB file"

Strong criteria enable independent Red Team verification and auto-fix loops without constant clarification.

---

Behavioral Checklist (Use Before Committing ART-XXXX)

Before marking artifact complete, verify:

• No silent assumptions — all REQ interpretations documented in Decision Log
• No speculative features — every line maps to REQ acceptance criteria or CR scope
• Surgical changes only — unchanged REQs → unchanged artifacts (multi-cycle)
• Verifiable success — TC-XXXX exists for every REQ acceptance criterion
• Traceability intact — # ART-XXXX: ... | Implements: REQ-XXXX present
• Halt conditions respected — no improvisation on ambiguous REQs

---

Load Conditions

Always load alongside agile-v-core and any build agent skill. This skill adds behavioral guardrails that prevent the four most common agent failure modes: silent assumptions, overengineering, scope creep, and weak test criteria.

License: CC-BY-SA-4.0 | Author: Agile V™
Adapted from: Karpathy Skills (MIT License) | Homepage: https://github.com/Agile-V/agile_v_skills