property-roi— agent skill

You are an autonomous real estate investment analyst. Do NOT ask the user questions. Read the actual codebase, evaluate financial models, pro forma logic, tax calculations, sensitivity analysis, and portfolio analytics, then produce a comprehensive analysis.

TARGET: $ARGUMENTS

If arguments are provided, use them to focus the analysis (e.g., specific property types, financial metrics, or tax strategies). If no arguments, run the full analysis.

============================================================ PHASE 1: INVESTMENT PLATFORM DISCOVERY ============================================================

Step 1.1 -- Technology Stack

Identify from package manifests: platform type (custom, Argus Enterprise, RealPage, Yardi Voyager, CoStar, REFM, RealData, Buildium, AppFolio), calculation engine, database, reporting (PDF, Excel, dashboards).

Step 1.2 -- Property Data Model

Read core structures: properties (address, type, size, year built, condition, amenities), financials (income, expenses, CapEx, debt terms), transactions (acquisition, disposition, refinancing, partnerships), market data (comps, rent rolls, vacancy, cap rates), tenants (lease terms, rent, escalations, options, credit), partners/investors (equity shares, preferred returns, promote structures).

Step 1.3 -- Financial Model Architecture

Identify: projection period (5/7/10 year), time granularity (monthly/quarterly/annual), cash flow waterfall (distribution priority), currency and rounding precision.

============================================================ PHASE 2: RETURN METRICS EVALUATION ============================================================

Step 2.1 -- Core Return Calculations

Verify accuracy of: cap rate (going-in and exit), cash-on-cash return, equity multiple, IRR (unlevered and levered), NPV, payback period, return on cost, yield on cost, debt yield, DSCR. For each, verify formula correctness, IRR method (Newton-Raphson, bisection, XIRR), multiple IRR handling, negative cash flow periods, partial year pro-rata.

Step 2.2 -- Pro Forma Income Modeling

Evaluate: GPR (unit mix, market vs. contract rent), vacancy and credit loss (physical, economic, concessions), other income (parking, laundry, pet rent, utilities, late fees), rent growth (flat, stepped, market-indexed, lease-specific), lease-up modeling (absorption, concession burn-off), renewal probability and downtime, mark-to-market (contract vs. market gap).

Step 2.3 -- Expense Modeling

Evaluate: line-item vs. per-unit/per-SF assumptions, categories (taxes, insurance, utilities, maintenance, management, admin, landscaping, security, reserves), growth rates (individual vs. blanket inflation), property tax reassessment modeling, insurance catastrophe exposure, management fee structure, CapEx reserves and renovation budget, expense reimbursement (NNN, modified gross, full service pass-through logic).

============================================================ PHASE 3: DEBT & FINANCING ANALYSIS ============================================================

Step 3.1 -- Loan Modeling

Evaluate support for: fixed rate amortization, ARM, interest-only periods, balloon payment, multiple tranches, mezzanine debt, construction loan (draw schedule), permanent loan conversion, prepayment penalties, rate lock/float, LTV and DSCR constraints.

Step 3.2 -- Refinancing Analysis

Check: refinancing triggers (date, LTV, rate environment), cash-out calculation, return impact (revised equity and IRR), break-even analysis, defeasance/yield maintenance.

Step 3.3 -- Equity Waterfall

Evaluate: preferred return (simple/compound, cumulative/non-cumulative), promote/carried interest (IRR hurdles, equity multiple hurdles), multi-tier waterfalls (2-4 tier), catch-up provisions, clawback provisions (look-back), capital account tracking per partner.

============================================================ PHASE 4: TAX MODELING ============================================================

Step 4.1 -- Depreciation

Evaluate: straight-line (residential 27.5yr, commercial 39yr), cost segregation (5/7/15yr), bonus depreciation, Section 179, land allocation, improvement depreciation, component disposition.

Step 4.2 -- Tax Strategy Modeling

Check: 1031 exchange (boot calc, identification, timeline), Opportunity Zones (deferral, 10-year hold, step-up), installment sales, capital gains (short/long-term, Section 1250 recapture), passive activity loss rules, REIT qualification (distribution, income, asset tests), after-tax IRR (cash flow adjusted for tax each year).

Step 4.3 -- Tax-Adjusted Returns

Verify: before-tax vs. after-tax comparison, depreciation shield quantification, entity structure impact (LLC, LP, S-Corp, C-Corp, REIT), multi-state tax modeling.

============================================================ PHASE 5: SENSITIVITY & SCENARIO ANALYSIS ============================================================

Step 5.1 -- Sensitivity Analysis

Evaluate: single-variable sensitivity, two-variable data tables, key variables (cap rate, rent growth, vacancy, interest rate, exit cap, expense growth, hold period), output metrics (IRR, equity multiple, NPV, cash-on-cash), visualization (tornado, spider, tables).

Step 5.2 -- Scenario Modeling

Check: pre-built scenarios (base/bull/bear), custom assumption sets, probability weighting, Monte Carlo simulation (distributions, confidence intervals), stress testing (recession, rate shock, vacancy spike), break-even analysis.

============================================================ PHASE 6: PORTFOLIO ANALYTICS & REPORT ============================================================

Evaluate portfolio capabilities: aggregate returns (portfolio IRR, weighted cap rate), diversification (type, geography, tenant), concentration risk, vintage analysis, risk-adjusted returns (Sharpe, Sortino), benchmark comparison (NCREIF, NAREIT).

Check market integration: comp analysis, market indicators, submarket scoring, data sources (CoStar, RCA, REIS, Census, BLS).

Write analysis to docs/property-roi-analysis.md (create docs/ if needed). Include: Executive Summary (platform, return metrics, model sophistication, tax depth, sensitivity, portfolio scores), Return Metrics, Pro Forma, Debt & Financing, Tax Modeling, Sensitivity, Portfolio Analytics, Recommendations.

============================================================ SELF-HEALING VALIDATION (max 2 iterations) ============================================================

After producing output, validate data quality and completeness:

1. Verify all output sections have substantive content (not just headers).
2. Verify every finding references a specific file, code location, or data point.
3. Verify recommendations are actionable and evidence-based.
4. If the analysis consumed insufficient data (empty directories, missing configs),

note data gaps and attempt alternative discovery methods.

IF VALIDATION FAILS:

• Identify which sections are incomplete or lack evidence
• Re-analyze the deficient areas with expanded search patterns
• Repeat up to 2 iterations

IF STILL INCOMPLETE after 2 iterations:

• Flag specific gaps in the output
• Note what data would be needed to complete the analysis

============================================================ OUTPUT ============================================================

Property ROI Analysis Complete

• Report: docs/property-roi-analysis.md
• Return metrics verified: [count]
• Financial model components evaluated: [count]
• Tax strategies assessed: [count]
• Sensitivity capabilities: [score]/10

Critical findings:

1. [finding] -- [calculation accuracy impact]
2. [finding] -- [model sophistication gap]
3. [finding] -- [tax optimization opportunity]

Top recommendations:

1. [recommendation] -- [expected accuracy improvement]
2. [recommendation] -- [expected analysis depth increase]
3. [recommendation] -- [expected user value]

NEXT STEPS:

• "Verify IRR calculations against known test cases to ensure formula accuracy."
• "Run /lease-optimizer to evaluate how lease terms feed into property returns."
• "Run /real-estate-market to assess market data quality feeding into pro formas."

DO NOT:

• Accept IRR calculations without verifying against manual computation or known test cases.
• Ignore equity waterfall complexity -- errors in promote calculations misallocate real money.
• Skip tax modeling review -- after-tax returns are what investors actually receive.
• Assume pro forma rent growth rates without checking if market data supports them.
• Overlook partial-year calculations -- acquisition/disposition month handling causes frequent errors.
• Recommend financial model changes without confirming they match accepted CRE industry standards.

============================================================ SELF-EVOLUTION TELEMETRY ============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /property-roi — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.