===STUB_DETECTION=== META: TYPE::SKILL VERSION::"1.0.0" STATUS::ACTIVE PURPOSE::Systematic_detection_of_placeholder_implementations ORIGIN::Derived_from_OCTAVE_MCP_audit_discovering_9_hidden_stubs
CORE_PRINCIPLE::"Not all placeholders leave obvious traces -> Silent failures most dangerous"
===PATTERN_TAXONOMY===
// Three severity patterns for stub detection
PATTERN_1_OBVIOUS::[ DETECTION::easy[grep_finds_immediately], SIGNALS::[ "raise NotImplementedError()", "# TODO:", "# FIXME:", "pass # stub", "pass # placeholder", "throw new Error('Not implemented')" ], SEARCH::"grep -r 'NotImplementedError|TODO:|FIXME:|pass\s*#' src/", SEVERITY::LOW[explicit_and_visible] ]
PATTERN_2_HIDDEN::[ DETECTION::moderate[requires_context_patterns], SIGNALS::[ "# For minimal implementation", "# For now, return", "# For now, skip", "# Reserved for future", "# Could implement", "# deferred to", "return full_data_but_set_lossy_true", "accept_parameter_but_never_use_it", "commented_out_function_calls" ], SEARCH::"grep -r 'minimal implementation|For now|deferred|reserved for future|Could implement' src/", SEVERITY::MEDIUM[misleading_but_discoverable] ]
PATTERN_3_SILENT::[ DETECTION::hard[requires_behavior_analysis], SIGNALS::[ "function_accepts_param_but_ignores_it", "returns_success_but_does_nothing", "metadata_claims_work_done_but_wasn't", "docstring_promises_feature_not_implemented", "API_parameter_documented_but_dead_code" ], SEARCH::manual_code_review[trace_params_through_functions], SEVERITY::HIGH[false_success_dangerous] ]
===SEARCH_STRATEGY===
// Execute in this order for comprehensive detection
PHASE_1_KEYWORD_SCAN::[ COMMANDS::[ "grep -rn 'NotImplementedError\|TODO:\|FIXME:' src/", "grep -rn 'raise.*Error.*not.*implement' src/", "grep -rn 'pass$' src/ | grep -v 'init'", "grep -rn '# stub\|# placeholder' src/" ], OUTPUT::list_of_obvious_stubs ]
PHASE_2_CONTEXT_SCAN::[ COMMANDS::[ "grep -rn 'minimal implementation\|For now' src/", "grep -rn 'deferred\|reserved for future' src/", "grep -rn 'Could implement\|not yet\|skip' src/", "grep -rn '# self\._.*().*commented' src/" ], OUTPUT::list_of_hidden_stubs ]
PHASE_3_DEAD_PARAMETER_SCAN::[ TECHNIQUE::find_params_accepted_but_unused, COMMANDS::[ "grep -rn 'def.param.:' src/ | xargs -I {} grep -L 'param' {}", "grep -rn '# .*=.Reserved\|# .=.*future' src/" ], MANUAL::trace_function_parameters_to_usage, OUTPUT::list_of_ignored_parameters ]
PHASE_4_DOCSTRING_VS_IMPLEMENTATION::[ TECHNIQUE::compare_promises_to_reality, SIGNALS::[ "docstring_says_validates_but_validation_None", "docstring_says_filters_but_returns_full", "docstring_says_transforms_but_returns_unchanged", "API_docs_claim_feature_code_ignores" ], OUTPUT::list_of_broken_promises ]
PHASE_5_METADATA_LIES::[ TECHNIQUE::check_return_metadata_truthfulness, SIGNALS::[ "lossy=True_but_nothing_removed", "fields_omitted=X_but_all_fields_present", "repairs=[]_but_fix=True_requested", "validated=True_but_no_validation_occurred" ], OUTPUT::list_of_false_functionality ]
===SEVERITY_CLASSIFICATION===
HIGH::[ CRITERIA::[ "Core_feature_bypassed", "Parameter_accepted_but_ignored", "Returns_success_but_doesn't_work", "UX_failure_user_thinks_it_worked" ], EXAMPLES::[ "schema_name_param_ignored->no_validation", "filter_mode_returns_full_document", "fix=true_repairs_nothing" ], ACTION::immediate_fix_or_explicit_error ]
MEDIUM::[ CRITERIA::[ "Feature_incomplete", "Commented_out_functionality", "Pass_statement_with_TODO", "Partial_implementation" ], EXAMPLES::[ "_load_builtin_schemas()_commented_out", "_validate_section()_is_just_pass", "load_schema()_returns_minimal_stub" ], ACTION::document_and_plan_implementation ]
LOW::[ CRITERIA::[ "Feature_deferred_and_documented", "Explicit_fallback_behavior", "Parameter_reserved_for_future" ], EXAMPLES::[ "output_format!=octave_shows_message", "tier_param_commented_as_reserved", "json/yaml_export_not_yet_implemented" ], ACTION::track_as_technical_debt ]
===AUDIT_REPORT_TEMPLATE===
STRUCTURE::[ SUMMARY::count_of_findings_by_severity, CRITICAL_PLACEHOLDERS::each_with[file,line,severity,issue,impact,context], SUMMARY_TABLE::quick_reference_all_findings, RECOMMENDATIONS::prioritized_by_severity, DISCOVERY_PATTERNS::document_which_patterns_found_what ]
EVIDENCE_REQUIREMENTS::[ SHOW::actual_code_snippet, EXPLAIN::why_its_a_stub_not_intentional, IMPACT::what_fails_for_users, CONTEXT::why_it_exists[deferred,oversight,technical_debt] ]
===INTEGRATION_COMMANDS===
// For Python codebases PYTHON_SCAN::" grep -rn 'NotImplementedError\|raise.*not.implement' src/ grep -rn 'pass$' src/ --include='.py' | grep -v 'init.py\|test_' grep -rn '# TODO\|# FIXME\|# stub\|# placeholder' src/ grep -rn 'For now\|minimal implementation\|deferred' src/ "
// For TypeScript codebases TYPESCRIPT_SCAN::" grep -rn 'throw.*not.*implement\|TODO:\|FIXME:' src/ grep -rn '// stub\|// placeholder\|// deferred' src/ grep -rn 'return.*as any' src/ // type erasure often hides stubs "
// For any codebase UNIVERSAL_SCAN::" grep -rn 'For now\|minimal\|reserved for future\|Could implement' src/ grep -rn 'not yet\|deferred\|skip.*validation' src/ "
===ANTI_PATTERNS===
VALIDATION_WITHOUT_SCHEMA::[ SIGNAL::"validator = Validator(schema=None)", IMPACT::"Validation runs but validates nothing", FIX::"Pass actual schema or raise if none provided" ]
FILTER_WITHOUT_FILTERING::[ SIGNAL::"return full_doc; lossy=True; fields_omitted=[X,Y]", IMPACT::"User thinks filtering happened but got everything", FIX::"Actually filter or set lossy=False" ]
REPAIR_WITHOUT_REPAIRING::[ SIGNAL::"if fix: pass # Could implement later", IMPACT::"User requests repairs, nothing happens", FIX::"Implement repairs or raise NotImplementedError" ]
PARAM_WITHOUT_USAGE::[ SIGNAL::"# tier = params.get('tier') # Reserved", IMPACT::"API accepts param that does nothing", FIX::"Use param or remove from API" ]
===WISDOM===
CORE_TRUTHS::[ "Silent_stubs->worse_than_explicit_errors", "Accepting_unused_params->misleading_API", "False_metadata->dangerous_user_trust", "Docstring_promises≠implementation_reality", "grep_catches_obvious->manual_review_catches_hidden", "Most_dangerous_stubs->return_success" ]
DETECTION_PHILOSOPHY::" The hardest stubs to find are those that:
- •Accept parameters but ignore them
- •Return success when they did nothing
- •Set metadata claiming work was done
- •Have docstrings promising unimplemented features
Always trace parameters from API to actual usage. "
===END===